一键配置黑名单¶
Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.
功能概述¶
提供黑名单模板的配置、读取及写入SIM卡接口，支持通过模板索引快速切换策略，简化黑名单规则的部署与生效。
一键配置黑名单API¶
头文件¶
easy_network_blacklist.h
函数概览¶
函数 |
说明 |
|---|---|
qapp_easy_nw_blacklist_tpl_set_config() |
配置指定索引的黑名单模板参数 |
qapp_easy_nw_blacklist_tpl_get_config() |
读取指定索引的黑名单模板参数 |
qapp_easy_nw_blacklist_tpl_write() |
将黑名单模板参数写入指定SIM卡 |
qapp_easy_nw_blacklist_tpl_read() |
从指定SIM卡读取已配置的黑名单模板索引 |
函数详解¶
qapp_easy_nw_blacklist_tpl_set_config¶
功能描述
配置指定索引的黑名单模板参数，将传入的黑名单配置参数写入目标模板。函数原型
qosa_uint32_t qapp_easy_nw_blacklist_tpl_set_config(const qapp_easy_nw_blacklist_param_t *tpl, qapp_easy_nw_blacklist_tpl_e tpl_idx);
参数说明
参数 |
输入/输出 |
类型 |
说明 |
|---|---|---|---|
tpl |
输入 |
const qapp_easy_nw_blacklist_param_t * |
待写入的黑名单模板参数；详见 qapp_easy_nw_blacklist_param_t |
tpl_idx |
输入 |
qapp_easy_nw_blacklist_tpl_e |
待配置的黑名单模板索引；详见 qapp_easy_nw_blacklist_tpl_e |
返回值说明
0：函数执行成功
其他值（详见 qapp_easy_nw_blacklist_tpl_error_e）：函数执行失败
qapp_easy_nw_blacklist_tpl_get_config¶
功能描述
读取指定索引的黑名单模板参数，将模板中存储的黑名单配置参数输出到目标结构体。函数原型
qosa_uint32_t qapp_easy_nw_blacklist_tpl_get_config(qapp_easy_nw_blacklist_param_t *tpl, qapp_easy_nw_blacklist_tpl_e tpl_idx);
参数说明
参数 |
输入/输出 |
类型 |
说明 |
|---|---|---|---|
tpl |
输入 |
qapp_easy_nw_blacklist_param_t * |
读取到的黑名单模板参数；详见 qapp_easy_nw_blacklist_param_t |
tpl_idx |
输入 |
qapp_easy_nw_blacklist_tpl_e |
待读取的黑名单模板索引；详见 qapp_easy_nw_blacklist_tpl_e |
返回值说明
0：函数执行成功
其他值（详见 qapp_easy_nw_blacklist_tpl_error_e）：函数执行失败
qapp_easy_nw_blacklist_tpl_write¶
功能描述
将黑名单模板参数写入指定SIM卡，使黑名单配置生效。函数原型
qosa_uint32_t qapp_easy_nw_blacklist_tpl_write(qosa_uint8_t simid, qapp_easy_nw_blacklist_tpl_e tpl_idx);
参数说明
参数 |
输入/输出 |
类型 |
说明 |
|---|---|---|---|
simid |
输入 |
qosa_uint8_t |
SIM ID |
tpl_idx |
输入 |
qapp_easy_nw_blacklist_tpl_e |
待写入的黑名单模板索引；详见 qapp_easy_nw_blacklist_tpl_e |
返回值说明
0：函数执行成功
其他值（详见 qapp_easy_nw_blacklist_tpl_error_e）：函数执行失败
qapp_easy_nw_blacklist_tpl_read¶
功能描述
从指定SIM卡读取已配置的黑名单模板索引。函数原型
qosa_uint32_t qapp_easy_nw_blacklist_tpl_read(qosa_uint8_t simid, qapp_easy_nw_blacklist_tpl_e *tpl_idx);
参数说明
参数 |
输入/输出 |
类型 |
说明 |
|---|---|---|---|
simid |
输入 |
qosa_uint8_t |
SIM ID |
tpl_idx |
输出 |
qapp_easy_nw_blacklist_tpl_e |
读取到的黑名单模板索引；详见 qapp_easy_nw_blacklist_tpl_e |
返回值说明
0：函数执行成功
其他值（详见 qapp_easy_nw_blacklist_tpl_error_e）：函数执行失败
结构体定义¶
qapp_easy_nw_blacklist_param_t¶
黑名单模板参数结构体定义如下：
/**
* @brief 网络黑名单配置模板 参数结构体
* @details 封装网络黑名单所需的全部配置参数，为黑名单模板提供完整的参数集
*/
typedef struct
{
qosa_nw_blacklist_param_t blacklist; /**< 网络黑名单核心配置参数：包含黑名单的规则、网段、优先级等配置项 */
} qapp_easy_nw_blacklist_param_t;
参数 |
类型 |
说明 |
|---|---|---|
blacklist |
qosa_nw_blacklist_param_t |
黑名单核心配置参数；详见 qosa_nw_blacklist_param_t |
qosa_nw_blacklist_param_t¶
/**
* @brief 网络黑名单 总配置参数结构体
* @details 整合公共配置+数据业务配置的完整黑名单配置结构体，作为黑名单配置的顶层数据结构
*/
typedef struct
{
qosa_nw_blacklist_common_settings_t common; /**< 网络黑名单公共通用配置项 */
qosa_nw_blacklist_data_service_settings_t data_service; /**< 网络黑名单数据业务专项配置项 */
} qosa_nw_blacklist_param_t;
qosa_nw_blacklist_common_settings_t¶
/**
* @brief 网络黑名单 公共通用配置结构体
* @details 网络黑名单核心公共配置项，包含黑名单总开关、超时、粘滞保护、故障计数等基础配置
*/
typedef struct
{
qosa_uint8_t enable; /**< 黑名单总功能开关 0-关闭 QOSA_NW_BLACKLIST_DISABLE，1-开启 QOSA_NW_BLACKLIST_ENABLE */
qosa_uint32_t timeout; /*!< 黑名单小区自动移除的超时时间，单位: 秒 */
qosa_uint8_t stuck_enable; /*!< 黑名单粘滞防卡死保护开关 0-关闭 1-开启 */
qosa_uint32_t stuck_timeout; /*!< 无注册行为后，黑名单小区加权释放超时时间，单位: 秒 */
qosa_uint8_t cnt_mode; /*!< 故障场景1-3的评估计数方式，0-连续计数 1-累计计数 */
qosa_uint8_t cnt_thresh; /*!< 故障场景1-3的触发计数阈值，取值范围:1~255 */
qosa_uint8_t osc_rounds; /**< 乒乓切换检测所需的振荡周期数，阈值范围1~255 */
qosa_uint32_t osc_cycle; /**< 乒乓切换振荡检测的观测时间窗口，单位：秒 */
qosa_nw_blacklist_policy_type_e event_policy[QOSA_NW_NAS_EVENT_MAX]; /**< 各NAS事件对应的黑名单触发策略，组合配置枚举值 */
} qosa_nw_blacklist_common_settings_t;
qosa_nw_blacklist_data_service_settings_t¶
/**
* @brief 网络黑名单 数据业务专项配置结构体
* @details 数据业务场景下的黑名单个性化配置项，适配数据业务拨号/传输类故障的黑名单策略
*/
typedef struct
{
qosa_uint8_t enable; /**< 数据业务黑名单功能开关 0-关闭 1-开启 */
qosa_uint32_t packet_cnt; /**< 数据业务故障的报文统计阈值 */
qosa_uint32_t packet_timeout; /**< 数据业务报文超时判定时间，单位：秒 */
qosa_uint32_t cfun_thresh; /**< 数据业务触发CFUN切换的阈值 */
qosa_uint8_t blacklist_action; /*!< 黑名单触发动作配置（该字段暂不支持） */
char host[QOSA_NW_BLACKLIST_HOST_MAX_SIZE]; /**< 数据业务黑名单对应的HOST地址/域名存储 */
} qosa_nw_blacklist_data_service_settings_t;
枚举类型定义¶
qapp_easy_nw_blacklist_tpl_error_e¶
/**
* @brief 网络黑名单配置模板 错误码枚举
* @details 网络黑名单模板相关所有接口的统一返回错误码，标识接口调用的执行结果状态
*/
typedef enum
{
QAPP_EASY_NW_BLACKLIST_TPL_SUCCESS = QOSA_OK, /**< 操作执行成功 */
QAPP_EASY_NW_BLACKLIST_TPL_EXECUTE_ERR = 1, /**< 通用执行失败错误 */
QAPP_EASY_NW_BLACKLIST_TPL_NO_MEMORY, /**< 内存分配失败，无可用内存空间 */
QAPP_EASY_NW_BLACKLIST_TPL_MISMATCH, /**< 配置模板与参数不匹配/索引无效错误 */
} qapp_easy_nw_blacklist_tpl_error_e;
qapp_easy_nw_blacklist_tpl_e¶
/**
* @brief 网络黑名单配置模板 索引枚举
* @details 区分系统内置黑名单模板和用户自定义黑名单模板，用于指定待操作的黑名单模板编号
*/
typedef enum
{
QAPP_EASY_NW_BLACKLIST_TPL_INTERNAL_NONE = -1, /**< 无效模板索引，无匹配的黑名单模板 */
/* 内部使用 - 系统内置模板 不可修改 */
QAPP_EASY_NW_BLACKLIST_TPL_INTERNAL_DEFAULT = 0, /**< 默认通用黑名单配置模板关闭 */
QAPP_EASY_NW_BLACKLIST_TPL_INTERNAL_DEFAULT_ENABLE, /**< 默认通用黑名单配置模板开启 */
QAPP_EASY_NW_BLACKLIST_TPL_INTERNAL_MAX, /**< 内置模板数量上限，内置/用户模板分界值 */
/* 用户自定义模板 支持自定义配置 可修改 可增加 */
QAPP_EASY_NW_BLACKLIST_TPL_USER_0 = QAPP_EASY_NW_BLACKLIST_TPL_INTERNAL_MAX, /**< 用户自定义黑名单模板0 */
QAPP_EASY_NW_BLACKLIST_TPL_USER_1, /**< 用户自定义黑名单模板1 */
QAPP_EASY_NW_BLACKLIST_TPL_USER_2, /**< 用户自定义黑名单模板2 */
QAPP_EASY_NW_BLACKLIST_TPL_MAX, /**< 所有黑名单模板总数上限(内置+用户) */
} qapp_easy_nw_blacklist_tpl_e;
qosa_nw_blacklist_params_e¶
/**
* @brief 网络黑名单功能 配置参数枚举(阈值/开关/最大值定义)
* @details 网络黑名单所有配置项的默认值、最大值、最小值、功能开关枚举常量定义，统一管理配置阈值范围
*/
typedef enum
{
QOSA_NW_BLACKLIST_CELL_MAX = 10, /**< 黑名单中可存储的小区最大数量 */
QOSA_NW_BLACKLIST_DISABLE = 0, /**< 黑名单功能：关闭 */
QOSA_NW_BLACKLIST_ENABLE = 1, /**< 黑名单功能：开启 */
/* Unit: s */
QOSA_NW_BLACKLIST_TIMEOUT_MIN = 300, /**< 小区黑名单自动移除超时最小值，单位：秒 */
QOSA_NW_BLACKLIST_TIMEOUT_MAX = 86400, /**< 小区黑名单自动移除超时最大值，单位：秒 */
QOSA_NW_BLACKLIST_TIMEOUT_DEFAULT = 1800, /**< 小区黑名单自动移除超时默认值，单位：秒 */
QOSA_NW_BLACKLIST_STUCK_DISABLE = 0, /**< 黑名单粘滞保护功能：关闭 */
QOSA_NW_BLACKLIST_STUCK_ENABLE = 1, /**< 黑名单粘滞保护功能：开启 */
/* Unit: s */
QOSA_NW_BLACKLIST_STUCK_TIMEOUT_MIN = 60, /**< 无注册小区黑名单加权释放超时最小值，单位：秒 */
QOSA_NW_BLACKLIST_STUCK_TIMEOUT_MAX = 3600, /**< 无注册小区黑名单加权释放超时最大值，单位：秒 */
QOSA_NW_BLACKLIST_STUCK_TIMEOUT_DEFAULT = 300, /**< 无注册小区黑名单加权释放超时默认值，单位：秒 */
QOSA_NW_BLACKLIST_CNT_MODE_CONSECUTIVE = 0, /**< 故障场景计数模式：连续计数 */
QOSA_NW_BLACKLIST_CNT_MODE_CUMULATIVE = 1, /**< 故障场景计数模式：累计计数 */
QOSA_NW_BLACKLIST_CNT_THRESH_MIN = 1, /**< 故障场景计数阈值最小值 */
QOSA_NW_BLACKLIST_CNT_THRESH_MAX = 255, /**< 故障场景计数阈值最大值 */
QOSA_NW_BLACKLIST_CNT_THRESH_DEFAULT = 5, /**< 故障场景计数阈值默认值 */
QOSA_NW_BLACKLIST_OSC_ROUNDS_MIN = 1, /**< 乒乓切换检测循环次数最小值 */
QOSA_NW_BLACKLIST_OSC_ROUNDS_MAX = 255, /**< 乒乓切换检测循环次数最大值 */
QOSA_NW_BLACKLIST_OSC_ROUNDS_DEFAULT = 3, /**< 乒乓切换检测循环次数默认值 */
/* Unit: s*/
QOSA_NW_BLACKLIST_OSC_PERIOD_MIN = 300, /**< 乒乓切换检测周期最小值，单位：秒 */
QOSA_NW_BLACKLIST_OSC_PERIOD_MAX = 32400, /**< 乒乓切换检测周期最大值，单位：秒 */
QOSA_NW_BLACKLIST_OSC_PERIOD_DEFAULT = 600, /**< 乒乓切换检测周期默认值，单位：秒 */
QOSA_NW_BLACKLIST_HOST_MAX_SIZE = 256, /**< 黑名单HOST域名/地址的最大字符长度 */
} qosa_nw_blacklist_params_e;
qosa_nw_blacklist_policy_type_e¶
/**
* @brief 网络黑名单 触发策略类型枚举
* @details 小区被加入黑名单后，对应的触发处理策略，支持位或组合配置多种策略
*/
typedef enum
{
QOSA_NW_BLACKLIST_POLICY_NONE = 0, /**< 无处理策略，仅加入黑名单 */
QOSA_NW_BLACKLIST_POLICY_TIMEOUT = 1 << 0, /**< 策略位：超时自动解除黑名单 */
QOSA_NW_BLACKLIST_POLICY_CFUN = 1 << 1, /**< 策略位：触发CFUN模式切换处理 */
QOSA_NW_BLACKLIST_POLICY_POWER_DOWN = 1 << 2, /**< 策略位：触发射频模块下电处理 */
} qosa_nw_blacklist_policy_type_e;