# 一键配置黑名单

***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

- **功能描述**  
  配置指定索引的黑名单模板参数，将传入的黑名单配置参数写入目标模板。

- **函数原型**

```c
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*](#qappeasynwblacklistparam_t) |
| *tpl_idx* | 输入 | *qapp_easy_nw_blacklist_tpl_e* | 待配置的黑名单模板索引；详见 [*qapp_easy_nw_blacklist_tpl_e*](#qappeasynwblacklisttpl_e) |

- **返回值说明**  
  *0*：函数执行成功  
  其他值（详见 [*qapp_easy_nw_blacklist_tpl_error_e*](#qappeasynwblacklisttplerrore)）：函数执行失败

### qapp_easy_nw_blacklist_tpl_get_config

- **功能描述**  
  读取指定索引的黑名单模板参数，将模板中存储的黑名单配置参数输出到目标结构体。

- **函数原型**

```c
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*](#qappeasynwblacklistparam_t) |
| *tpl_idx* | 输入 | *qapp_easy_nw_blacklist_tpl_e* | 待读取的黑名单模板索引；详见 [*qapp_easy_nw_blacklist_tpl_e*](#qappeasynwblacklisttpl_e) |

- **返回值说明**  
  *0*：函数执行成功  
  其他值（详见 [*qapp_easy_nw_blacklist_tpl_error_e*](#qappeasynwblacklisttplerrore)）：函数执行失败

### qapp_easy_nw_blacklist_tpl_write

- **功能描述**  
  将黑名单模板参数写入指定SIM卡，使黑名单配置生效。

- **函数原型**

```c
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*](#qappeasynwblacklisttpl_e) |

- **返回值说明**  
  *0*：函数执行成功  
  其他值（详见 [*qapp_easy_nw_blacklist_tpl_error_e*](#qappeasynwblacklisttplerrore)）：函数执行失败

### qapp_easy_nw_blacklist_tpl_read

- **功能描述**  
  从指定SIM卡读取已配置的黑名单模板索引。

- **函数原型**

```c
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*](#qappeasynwblacklisttpl_e) |

- **返回值说明**  
  *0*：函数执行成功  
  其他值（详见 [*qapp_easy_nw_blacklist_tpl_error_e*](#qappeasynwblacklisttplerrore)）：函数执行失败

## 结构体定义

### qapp_easy_nw_blacklist_param_t

黑名单模板参数结构体定义如下：

```cpp
/**
 * @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*](#qosanwblacklistparamt) |

### qosa_nw_blacklist_param_t

```cpp
/**
 * @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

```cpp
/**
 * @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

```cpp
/**
 * @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

```cpp
/**
 * @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

```cpp
/**
 * @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

```cpp
/**
 * @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

```cpp
/**
 * @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;
```

# 应用示例代码

## 一键黑名单默认参数配置

https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/application/one_touch/blacklist/blacklist_demo.c

## 使用内置黑名单配置

https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/application/one_touch/blacklist/blacklist_builtin.c