# SIM
***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***
---
# 概述
Subscriber Identity Module，简称SIM，是一种基于智能卡技术的安全存储设备，主要用于存储用户身份标识、鉴权密钥、运营商数据以及个人通讯录等信息。SIM通过标准化的文件系统结构（如MF、DF、EF）组织数据，并遵循3GPP/ETSI规范，支持多种物理形态（2FF/3FF/4FF）。SIM与移动设备（ME）通过ISO/IEC 7816接口进行通信，其数据访问和安全性管理是移动通信的核心基础。
## SIM包括以下几个基本要素
1. **ICCID (集成电路卡识别码)**：SIM卡的唯一身份标识，印刷在卡体上，也存储在卡内文件中。用于运营商识别卡本身。
2. **IMSI (国际移动用户识别码)**：用户的唯一身份标识，存储在卡内，是网络识别用户、进行鉴权的核心。通常不会直接显示给用户。
3. **鉴权密钥 (Ki)** ：与IMSI对应的128位密钥，预先共享在SIM卡和运营商网络鉴权中心（AuC）中，用于生成鉴权响应的核心机密，绝不由SIM卡读出。
4. **文件系统**：SIM卡内部采用层级文件系统（MF/DF/EF）来组织数据，如短信存储文件（EF `SMS`）、电话簿文件（EF `ADN`）、网络参数文件（EF `LOCI`）等。
5. **PIN/PUK码**：个人识别码（PIN）用于保护SIM卡不被非法使用；其解锁码（PUK）用于在PIN码输入错误被锁定时进行解锁。
## SIM流程概述
SIM流程是指移动设备通过标准化接口与SIM进行交互的完整过程。该流程涵盖物理层检测、初始化配置、安全认证及数据访问，确保设备能够安全、可靠地获取用户身份及网络接入参数。
SIM流程通常包含以下几个关键步骤：
1. 物理检测与上电（Physical Detection & Power-on）：
- 设备通过卡槽触点检测SIM物理在位状态（如 `qosa_sim_read_slot_stat()`）。
- 设备为SIM提供额定电压（1.8V/3V/5V），并触发冷复位流程，接收ATR（Answer to Reset）响应以识别卡类型（如 `qosa_sim_read_sim_type()`）。
2. 初始化与状态同步（Initialization & Status Sync）：
- 设备读取SIM功能块初始化状态（`qosa_sim_read_init_stat()`）及插入状态（`qosa_sim_read_insert_stat()`）。
- 同步获取SIM当前状态信息，包括是否就绪、PIN锁定状态等（`qosa_sim_read_status()` 或 `qosa_sim_get_status()`）。
3. 安全鉴权（Security Authentication）：
- 设备从SIM读取IMSI（`qosa_sim_read_imsi()`）并提交至网络。
- 网络返回随机数RAND，SIM利用内部鉴权算法计算响应值SRES和密钥Kc，完成双向身份验证。
4. 数据访问与管理（Data Access & Management）：
- 根据业务需求，设备读取或更新SIM内数据，如ICCID（`qosa_sim_read_iccid()`）、本机号码（`qosa_sim_get_phonenumber()`）等。
- 涉及敏感操作时，需验证PIN（`qosa_sim_verify_pin()`）或修改PIN（`qosa_sim_change_pin()`）。
5. 通道管理与高级访问（Channel Management & Advanced Access）：
- 对于复杂应用，设备可打开逻辑通道（`qosa_sim_open_logical_channel()`）建立独立会话。
- 通过逻辑通道访问（`qosa_sim_generic_logical_channel_access()`）或限制访问接口（`qosa_sim_restricted_access()`）执行自定义APDU指令。
- 操作完成后关闭逻辑通道（`qosa_sim_close_logical_channel()`）释放资源。
6. 热插拔与动态配置（Hot-swap & Dynamic Config）：
- 设备可配置热插拔检测功能（`qosa_sim_set_sim_hot_swap()`），实时监控SIM插拔事件。
- 获取当前物理卡槽映射关系（`qosa_sim_get_slot_id()`）或动态切换卡槽（`qosa_sim_set_slot_id()`）支持多卡管理。
7. 错误处理与重试机制（Error Handling & Retry）：
- 若PIN验证失败，查询剩余重试次数（`qosa_sim_get_pin_remain_retries()`），超过阈值需使用PUK解锁（`qosa_sim_unblock_pin()`）。
- 对于facility锁（如FD锁），支持获取状态（`qosa_sim_get_facility_lock()`）和设置（`qosa_sim_set_facility_lock()`）以控制功能访问。
## SIM访问模式
SIM操作通常分为直接API模式和通用接入模式，两者在易用性和灵活性上各有侧重。
### 直接API模式
基本概念：一种面向开发者的高级封装模式，提供简洁的同步/异步接口访问SIM标准数据。开发者无需关心底层APDU指令构造，由模块自动完成协议交互。
工作原理：
- 数据读取：调用如 `qosa_sim_read_imsi()` 或 `qosa_sim_read_iccid()` 等接口，模块内部自动发送相应APDU指令并解析响应，返回结构化数据。
- 状态查询：使用 `qosa_sim_read_status()` 直接获取SIM就绪状态，无需手动解析状态字节。
- 配置管理：通过 `qosa_sim_set_sim_hot_swap()` 等接口一键配置功能，模块处理参数校验和指令下发。
优点：
1. 开发高效：接口语义明确，屏蔽底层复杂度，大幅缩短开发周期。
2. 稳定可靠：由模块厂商预置标准流程，规避常见协议错误。
3. 易于维护：代码可读性强，升级和维护成本低。
缺点：
1. 灵活性受限：仅支持预定义的标准数据访问，无法执行自定义指令。
2. 扩展性差：对于非标准EF文件或运营商专有指令，无法直接调用。
3. 透明性不足：底层交互细节不可见，难以深度优化或故障诊断。
### 通用接入模式
基本概念：一种面向协议的底层访问模式，提供APDU级透明通道。开发者需手动构造和解析符合ISO/IEC 7816标准的完整指令串，实现对SIM的完全控制。
工作原理：
- 指令构造：开发者需手动组装APDU指令，包括CLA、INS、P1、P2、Lc、Data、Le等字段。
- 通用接入：通过 `qosa_sim_generic_access()` 发送原始APDU，模块仅作为传输通道返回响应数据和状态字（SW1/SW2）。
- 逻辑通道：使用 `qosa_sim_open_logical_channel()` 创建独立会话，通过 `qosa_sim_generic_logical_channel_access()` 在多应用间并行操作。
- 限制访问：`qosa_sim_restricted_access()` 提供更细粒度的安全控制，适用于敏感数据操作。
优点：
1. 完全控制：可访问任意EF文件，执行任意标准或私有指令，支持深度定制。
2. 功能强大：可实现STK（SIM ToolKit）、安全域管理、OTA远程更新等高级功能。
3. 调试透明：可获取原始响应数据，便于协议分析和问题定位。
缺点：
1. 开发复杂：需精通SIM文件结构、安全状态机及APDU编码规范。
2. 调试困难：指令构造错误或状态迁移不当易导致卡锁死或数据损坏。
3. 兼容性风险：不同厂商SIM对指令扩展支持存在差异，需针对性适配。
---
模式选择建议：常规业务（如读取IMSI、ICCID、号码本）推荐使用直接API模式；高级应用（如STK、OTA、安全算法调用）或协议调试场景推荐使用通用接入模式。
# API说明
## 头文件
`qosa_sim.h`
## 函数列表
| **函数** | **描述** |
| --- | --- |
| `qosa_sim_read_sim_type()` | 读取SIM卡类型信息 |
| `qosa_sim_get_imsi()` | 异步获取IMSI |
| `qosa_sim_read_imsi()` | 同步获取IMSI |
| `qosa_sim_get_status()` | 异步获取SIM卡状态信息 |
| `qosa_sim_read_status()` | 同步获取SIM卡状态信息 |
| `qosa_sim_read_init_stat()` | 获取SIM卡功能块初始化状态 |
| `qosa_sim_read_insert_stat()` | 获取SIM卡插入状态 |
| `qosa_sim_read_slot_stat()` | 获取物理层卡槽SIM卡的在位状态 |
| `qosa_sim_set_sim_hot_swap()` | 设置SIM卡热插拔检测功能 |
| `qosa_sim_get_sim_hot_swap()` | 获取SIM卡热插拔检测功能配置 |
| `qosa_sim_get_slot_id()` | 获取应用层simid对应使用的物理卡槽 |
| `qosa_sim_set_slot_id()` | 设置应用层simid对应使用的物理卡槽 |
| `qosa_sim_verify_pin()` | 核查PIN码 |
| `qosa_sim_unblock_pin()` | 重置PIN码 |
| `qosa_sim_change_pin()` | 修改PIN码 |
| `qosa_sim_get_pin_remain_retries()` | 获取SIM卡PIN码剩余次数 |
| `qosa_sim_get_facility_lock()` | 获取FAC锁状态 |
| `qosa_sim_set_facility_lock()` | 设置FAC锁 |
| `qosa_sim_generic_access()` | SIM卡通用接入接口 |
| `qosa_sim_generic_logical_channel_access()` | SIM卡逻辑通道访问 |
| `qosa_sim_restricted_access()` | SIM卡限制访问接口 |
| `qosa_sim_get_iccid()` | 异步获取ICCID |
| `qosa_sim_read_iccid()` | 同步获取ICCID |
| `qosa_sim_open_logical_channel()` | 打开一个逻辑通道 |
| `qosa_sim_close_logical_channel()` | 关闭一个逻辑通道 |
| `qosa_sim_get_phonenumber()` | 获取SIM卡里的电话号码 |
## 函数定义
### 读取SIM卡类型信息
#### qosa_sim_read_sim_type
#### 函数原型
```c
qosa_sim_type_e qosa_sim_read_sim_type(qosa_uint8_t simid)
```
#### 功能描述
此功能用于同步读取指定SIM卡的卡类型信息，包括SIM卡和USIM卡类型。通过此功能，您可以获取当前SIM卡的具体类型，用于区分2G SIM卡和3G/4G/5G USIM卡。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| simid | qosa_uint8_t | 是 | 0~1 | SIM卡ID |
#### 返回值说明
- `QOSA_SIM_TYPE_INVALID`：无效SIM类型
- `QOSA_SIM`：普通SIM卡（2G）
- `QOSA_USIM`：USIM卡（3G/4G/5G）
```{note}
**注意：**
1. 此函数只能在SIM卡初始化完成后使用，否则可能返回错误结果。
2. 此函数为同步操作，会立即返回结果。
3. 在双卡场景下，需要指定正确的SIM ID来查询对应SIM卡的状态。
```
### 异步获取IMSI
#### qosa_sim_get_imsi
#### 函数原型
```c
qosa_sim_err_e qosa_sim_get_imsi(qosa_uint8_t simid, sim_callback_ptr cb, void *ctx);
```
#### 功能描述
此函数用于异步读取SIM卡的IMSI（国际移动用户识别码）信息。
IMSI是SIM卡的唯一标识符，用于在移动网络中识别用户身份。
该操作异步执行，结果通过回调函数返回。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| simid | qosa_uint8_t | 是 | 0~1 | SIM卡ID |
| cb | `sim_callback_ptr` | 是 | 无 | 回调函数指针，用于接收操作结果
回调参数类型：`qosa_sim_get_imsi_cnf_t`
成功时返回IMSI字符串，失败时返回错误代码 |
| ctx | void * | 是 | 无 | 用户上下文指针，将在回调时按原样传递 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_BUSY`：SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
- `QOSA_SIM_ERR_FAILURE`: 查询失败
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为异步操作，实际执行结果通过回调函数返回。
2. IMSI通常为15位数字字符串，格式为：MCC（3位）+ MNC（2-3位）+ MSIN（9-10位）。
3. 调用此函数前，建议检查 SIM 卡状态是否已准备就绪（`QOSA_SIM_STATUS_READY`）。
```
### 同步获取IMSI
#### qosa_sim_read_imsi
#### 函数原型
```c
qosa_sim_err_e qosa_sim_read_imsi(qosa_uint8_t simid, qosa_sim_imsi_t *imsi);
```
#### 功能描述
此函数用于同步读取SIM卡的IMSI（国际移动用户识别码）信息。
IMSI是SIM卡的唯一标识符，用于在移动网络中识别用户身份。
此函数将直接返回读取结果，适用于需要立即获取IMSI的场景。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| simid | qosa_uint8_t | 是 | 0~1 | SIM卡ID |
| imsi | `qosa_sim_imsi_t` * | 是 | 无 | 指向IMSI结构的指针，用于接收读取的IMSI信息
IMSI以字符串格式存储在该结构中
调用者需要确保传入的指针有效 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_BUSY`：SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
- `QOSA_SIM_ERR_FAILURE`: 查询失败
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为同步操作，会阻塞当前线程直至操作完成。
2. IMSI通常为15位数字字符串，格式为：MCC（3位）+ MNC（2-3位）+ MSIN（9-10位）。
3. 调用此函数前，建议检查SIM卡状态是否已准备就绪（`QOSA_SIM_STATUS_READY`）。
```
### 异步获取SIM卡状态信息
#### qosa_sim_get_status
#### 函数原型
```c
qosa_sim_err_e qosa_sim_get_status(qosa_uint8_t simid, sim_callback_ptr cb, void *ctx);
```
#### 功能描述
此函数用于异步查询SIM卡的当前状态信息，包括PIN码状态、锁定状态等。
根据平台特性，此操作可能需要与CP端交互，结果通过回调函数返回。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| simid | qosa_uint8_t | 是 | 0~1 | SIM卡ID |
| cb | `sim_callback_ptr` | 是 | 无 | 回调函数指针，用于接收操作结果
回调参数类型：`qosa_sim_get_status_cnf_t`
成功时返回SIM卡状态信息，失败时返回错误代码 |
| ctx | void * | 是 | 无 | 用户上下文指针，将在回调时按原样传递 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_BUSY`：SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
- `QOSA_SIM_ERR_FAILURE`: 查询失败
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为异步操作，实际执行结果通过回调函数返回。
2. 返回的状态信息包括SIM卡的当前状态（例如READY、SIM PIN、SIM PUK等）。
3. 在双卡场景下，需要指定正确的SIM卡ID来查询对应SIM卡的状态。
```
### 同步获取SIM卡状态信息
#### qosa_sim_read_status
#### 函数原型
```c
qosa_sim_err_e qosa_sim_read_status(qosa_uint8_t simid, qosa_sim_status_e *status);
```
#### 功能描述
此函数用于同步读取缓存的SIM卡状态信息，无需与底层交互。
它返回最新更新的SIM卡状态，适用于需要快速访问状态信息的场景。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| simid | qosa_uint8_t | 是 | 0~1 | SIM卡ID |
| status | `qosa_sim_status_e` * | 是 | 无 | 指向状态枚举变量的指针，用于接收读取的SIM卡状态
状态值参考 `qosa_sim_status_e` 枚举定义
调用方需要确保传入有效的指针 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_BUSY`：SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
- `QOSA_SIM_ERR_FAILURE`: 查询失败
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为同步操作，会阻塞当前线程直至操作完成。
2. 返回的状态是缓存的SIM卡状态，可能并非实时状态。
3. 如需获取实时状态，请使用异步接口。
4. 常见状态包括：READY、SIM PIN、SIM PUK、NOT_INSERTED等。
```
### 获取SIM卡功能块初始化状态
#### qosa_sim_read_init_stat
#### 函数原型
```c
int qosa_sim_read_init_stat(qosa_uint8_t simid);
```
#### 功能描述
此函数用于查询指定SIM卡功能模块的初始化状态，返回值是多个状态标志位的组合。
您可以通过位运算来检查每个功能模块是否已完成初始化。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| simid | qosa_uint8_t | 是 | 0~1 | SIM卡ID |
#### 返回值说明
返回值是以下状态标志位的组合（按位或）：
- `QOSA_SIMINI_STAT_START`：SIM卡初始化开始状态
- `QOSA_SIMINI_STAT_CPIN_READY`：SIM卡PIN码就绪状态
- `QOSA_SIMINI_STAT_SMS_DONE`: 短信功能初始化完成状态
- `QOSA_SIMINI_STAT_PB_DONE`: 电话簿功能初始化完成状态
```{note}
**注意：**
1. 此函数为同步操作，将立即返回结果。
2. 返回值是多个状态标志位的组合，需要使用位运算进行解析。
3. 不同的状态标志位可能在不同的时间点被设置，反映SIM卡初始化的不同阶段。
```
### 获取SIM卡插入状态
#### qosa_sim_read_insert_stat
#### 函数原型
```c
qosa_sim_insert_stat_e qosa_sim_read_insert_stat(qosa_uint8_t simid);
```
#### 功能描述
此函数用于查询指定SIM卡的插入状态，主要用于单卡单待和双卡双待场景。
在双卡单待场景中，如果需要获取未激活SIM卡的插入状态，请使用SLOT_INSERT相关接口。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| simid | qosa_uint8_t | 是 | 0~1 | SIM卡ID |
#### 返回值说明
- `QOSA_SIM_INSERT_STAT_REMOVED`：SIM卡已移除
- `QOSA_SIM_INSERT_STAT_INSERTED`：SIM卡已插入
- `QOSA_SIM_INSERT_STAT_UNKNOWN`: SIM卡状态未知
```{note}
**注意：**
1. 此函数为同步操作，将立即返回结果。
2. 在双卡单待场景下，此接口只能获取当前已激活SIM卡的插入状态。
3. 对于未激活SIM卡的状态查询，请使用 `qosa_sim_read_slot_stat` 接口。
```
### 获取物理层卡槽SIM卡的在位状态
#### qosa_sim_read_slot_stat
#### 函数原型
```c
qosa_sim_insert_stat_e qosa_sim_read_slot_stat(qosa_uint8_t slotid);
```
#### 功能描述
此函数用于查询指定物理卡槽的SIM卡插入状态，与当前激活的SIM卡无关。
它可用于获取任何物理卡槽（包括未激活的卡槽）的SIM卡插入状态。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| slotid | qosa_uint8_t | 是 | 0~1 | 物理卡槽ID，用于标识要查询的物理卡槽 |
#### 返回值说明
- `QOSA_SIM_INSERT_STAT_REMOVED`：SIM卡已移除
- `QOSA_SIM_INSERT_STAT_INSERTED`：SIM卡已插入
- `QOSA_SIM_INSERT_STAT_UNKNOWN`: SIM卡状态未知
```{note}
**注意：**
1. 此函数为同步操作，将立即返回结果。
2. 此接口查询物理卡槽的状态，与当前激活的SIM卡无关。
3. 在双卡单待场景下，您可以使用此接口获取未激活卡槽的状态。
4. 卡槽编号与硬件设计相关，请参考具体硬件文档。
```
### 设置SIM卡热插拔检测功能
#### qosa_sim_set_sim_hot_swap
#### 函数原型
```c
qosa_sim_err_e qosa_sim_set_sim_hot_swap(qosa_uint8_t slotid, qosa_sim_hot_swap_cfg_t *hot_swap_config);
```
#### 功能描述
此函数用于配置指定物理卡槽的SIM卡热插拔检测功能，包括启用状态、插入检测级别和GPIO引脚配置。
热插拔检测功能使设备能够在SIM卡插入或移除时自动检测状态变化并触发相应的事件。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| slotid | qosa_uint8_t | 是 | 0~1 | 物理卡槽ID，用于标识要查询的物理卡槽 |
| hot_swap_config | `qosa_sim_hot_swap_cfg_t` * | 是 | 无 | 指向热插拔配置结构的指针，包含以下配置参数：
enable：是否启用热插拔检测功能
insert_level：SIM卡插入时检测引脚电平的状态
gpio：用于热插拔检测的GPIO引脚编号（如果支持配置，否则使用默认配置）
调用方需要确保传入有效的指针 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_INVALID_PARAM`：参数无效
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
- `QOSA_SIM_ERR_OPERATION_NOT_SUPPORTED`: 不支持此操作
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 根据产品平台特性，此接口可能立即生效，也可能在重启后生效。
2. 在双卡单待/双卡双待模式下，如果通过 `qosa_sim_set_slot_id` 交换卡槽，请注意应用层SIM ID与实际物理卡槽对应关系的变化。
3. 在大多数平台上，热插拔的启用和检测级别配置不区分卡槽ID，后一个配置优先。也就是说，如果您先通过此API配置卡槽ID 0启用热插拔功能，检测级别为高，然后再通过此API配置卡槽ID 1启用热插拔功能，检测级别为低，则实际热插拔的检测级别为低。
4. 此函数为同步操作，会立即返回结果。
```
### 获取SIM卡热插拔检测功能配置
#### qosa_sim_get_sim_hot_swap
#### 函数原型
```c
qosa_sim_err_e qosa_sim_get_sim_hot_swap(qosa_uint8_t slotid, qosa_sim_hot_swap_cfg_t *hot_swap_config);
```
#### 功能描述
此函数用于读取指定物理卡槽的SIM卡热插拔检测功能配置信息。
您可以获取热插拔功能的当前启用状态、插入检测级别和GPIO引脚配置。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| slotid | qosa_uint8_t | 是 | 0~1 | 物理卡槽ID，用于标识要查询的物理卡槽 |
| hot_swap_config | `qosa_sim_hot_swap_cfg_t` * | 是 | 无 | 指向热插拔配置结构的指针，用于接收配置信息
包含以下配置参数：
enable：是否启用热插拔检测功能
insert_level：SIM卡插入时检测引脚电平的状态
gpio：用于热插拔检测的GPIO引脚编号（如果支持配置）
调用方需要确保传入有效的指针 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_INVALID_PARAM`：参数无效
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
- `QOSA_SIM_ERR_OPERATION_NOT_SUPPORTED`: 不支持此操作
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为同步操作，会立即返回结果。
2. 热插拔检测配置可能因产品平台而异，部分平台可能不支持GPIO引脚配置。
3. 在多卡场景下，请注意应用层SIMID与物理卡槽的对应关系。
```
### 获取应用层simid对应使用的物理卡槽
#### qosa_sim_get_slot_id
#### 函数原型
```c
qosa_sim_err_e qosa_sim_get_slot_id(qosa_uint8_t simid, qosa_uint8_t *slotid);
```
#### 功能描述
此函数用于查询指定应用层SIM卡ID当前使用的物理卡槽ID。
主要用于双卡单待场景，帮助应用层理解SIM卡与物理卡槽之间的映射关系。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| simid | qosa_uint8_t | 是 | 0~1 | 应用层SIM ID，用于识别要查询的SIM卡
在双卡单待模式下，此参数通常为0（仅支持单卡） |
| slotid | qosa_uint8_t * | 是 | 0~1 | 指向物理卡槽ID的指针，用于接收查询结果
返回值是SIM卡当前使用的物理卡槽编号：
0：卡槽1（根据硬件设计文档定义）
1：卡槽2（根据硬件设计文档定义）
调用方需要确保传入有效的指针 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_INVALID_PARAM`：参数无效
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM 卡未插入
- `QOSA_SIM_ERR_OPERATION_NOT_SUPPORTED`: 不支持此操作
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为同步操作，会立即返回结果。
2. 在双卡单待模式下，应用层通常只能看到SIMID 0。
3. 物理卡槽编号与硬件设计相关，请参考具体硬件文档。
```
### 设置应用层simid对应使用的物理卡槽
#### qosa_sim_set_slot_id
#### 函数原型
```c
qosa_sim_err_e qosa_sim_set_slot_id(qosa_uint8_t simid, qosa_uint8_t slotid);
```
#### 功能描述
此功能用于配置指定应用层SIM ID所使用的物理卡槽，支持双卡单待场景下的卡槽切换。
在双卡双待场景下，此操作将触发底层SIM ID 0/1所使用的物理卡槽的交换。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| simid | qosa_uint8_t | 是 | 0~1 | 应用层SIM ID，用于识别要查询的SIM卡
在双卡单待模式下，此参数通常为0（仅支持单卡） |
| slotid | qosa_uint8_t | 是 | 0~1 | 目标物理卡槽ID，指定要使用的物理卡槽:
0：卡槽1（根据硬件设计文档定义）
1：卡槽2（根据硬件设计文档定义） |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_INVALID_PARAM`：参数无效
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
- `QOSA_SIM_ERR_OPERATION_NOT_SUPPORTED`: 不支持此操作
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为同步操作，会立即返回结果。
2. 在双卡单待模式下，应用层通常只能看到SIMID 0。
3. 物理卡槽编号与硬件设计相关，请参考具体硬件文档。
```
### 核查PIN码
#### qosa_sim_verify_pin
#### 函数原型
```c
qosa_sim_err_e qosa_sim_verify_pin(qosa_uint8_t simid, qosa_sim_pin_t *pin, sim_callback_ptr cb, void *ctx);
```
#### 功能描述
此函数用于异步验证SIM卡的PIN码，确认用户输入的PIN码是否正确。
该操作异步执行，并通过回调函数返回结果，指示验证是否成功。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| simid | qosa_uint8_t | 是 | 0~1 | SIM卡ID，用于识别SIM卡以进行验证 |
| pin | `qosa_sim_pin_t` * | 是 | 无 | 指向PIN码结构的指针，其中包含要验证的PIN码信息
PIN码必须是4到8位数字字符串
对于PIN1验证，通常使用4位数字
调用方需要确保传入有效的指针 |
| cb | `sim_callback_ptr` | 是 | 无 | 回调函数指针，用于接收操作结果
回调参数类型：`qosa_sim_general_cnf_t`
操作成功时返回操作成功状态，操作失败时返回错误代码 |
| ctx | void * | 是 | 无 | 用户上下文指针，将在回调时按原样传递 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_INVALID_PARAM`：参数无效
- `QOSA_SIM_ERR_BUSY`: SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为异步操作，实际执行结果通过回调函数返回。
2. 如果PIN码验证失败，SIM卡可能已被锁定，需要使用PUK码解锁。
3. 建议在验证前查询剩余的PIN码重试次数。
```
### 重置PIN码
#### qosa_sim_unblock_pin
#### 函数原型
```c
qosa_sim_err_e qosa_sim_unblock_pin(
qosa_uint8_t simid,
qosa_sim_pin_t *unblock_pin,
qosa_sim_pin_t *new_pin,
sim_callback_ptr cb,
void *ctx
);
```
#### 功能描述
此函数用于使用PUK码异步解锁已锁定的SIM卡并设置新的PIN码。
当PIN码输入错误次数超过限制导致SIM卡被锁定时，您需要使用PUK码解锁。
此操作异步执行，结果通过回调函数返回。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| simid | qosa_uint8_t | 是 | 0~1 | SIM卡ID，用于识别要操作的SIM卡 |
| unblock_pin | `qosa_sim_pin_t` * | 是 | 无 | 指向PUK码结构的指针，其中包含用于解锁的PUK码
PUK码必须是8位数字字符串
调用者需要确保传入有效的指针 |
| new_pin | `qosa_sim_pin_t` * | 是 | 无 | 指向包含待设置新PIN码的新PIN码结构的指针
新PIN码必须是4到8位数字字符串
调用方需要确保传入有效的指针 |
| cb | `sim_callback_ptr` | 是 | 无 | 回调函数指针，用于接收操作结果
回调参数类型：`qosa_sim_general_cnf_t`
操作成功时返回操作成功状态，操作失败时返回错误代码 |
| ctx | void * | 是 | 无 | 用户上下文指针，将在回调时按原样传递 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_INVALID_PARAM`：参数无效
- `QOSA_SIM_ERR_BUSY`: SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
- `QOSA_SIM_ERR_PUK_REQUIRED`: 需要PUK码
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为异步操作，实际执行结果通过回调函数返回。
2. PUK码通常印在SIM卡座上，如果PUK码输入错误次数超过限制，SIM卡将被永久锁定。
3. 建议操作前查询剩余的PUK码重试次数。
```
### 修改PIN码
#### qosa_sim_change_pin
#### 函数原型
```c
qosa_sim_err_e qosa_sim_change_pin(
qosa_uint8_t simid,
qosa_sim_facility_e fac,
qosa_sim_pin_t *old_pin,
qosa_sim_pin_t *new_pin,
sim_callback_ptr cb,
void *ctx
);
```
#### 功能描述
此函数用于异步更改SIM卡上特定设备的PIN码，例如PIN1、PIN2等。
需要输入旧PIN码进行验证，然后设置新PIN码。
此操作异步执行，结果通过回调函数返回。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| simid | qosa_uint8_t | 是 | 0~1 | SIM卡ID，用于识别要操作的SIM卡 |
| fac | `qosa_sim_facility_e` | 是 | 无 | 设施类型，请参考 `qosa_sim_facility_e` 枚举
常用设施包括：SC（SIM卡PIN1）、P2（PIN2）等
支持的功能类型取决于SIM卡和平台的功能 |
| old_pin | `qosa_sim_pin_t` * | 是 | 无 | 指向包含当前有效PIN码的旧PIN码结构的指针
用于验证用户是否拥有更改PIN码的权限
调用方必须确保传递有效的指针 |
| new_pin | `qosa_sim_pin_t` * | 是 | 无 | 指向包含待设置新PIN码的新PIN码结构的指针
新PIN码必须是4到8位数字字符串
调用方需要确保传入有效的指针 |
| cb | `sim_callback_ptr` | 是 | 无 | 回调函数指针，用于接收操作结果
回调参数类型：`qosa_sim_general_cnf_t`
操作成功时返回操作成功状态，操作失败时返回错误代码 |
| ctx | void * | 是 | 无 | 用户上下文指针，将在回调时按原样传递 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_INVALID_PARAM`：参数无效
- `QOSA_SIM_ERR_BUSY`: SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
- `QOSA_SIM_ERR_INCORRECT_PASSWORD`: 密码错误
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为异步操作，实际执行结果通过回调函数返回。
2. 更改PIN2等设置可能需要先验证PIN1。
3. 建议定期更改PIN码以提高安全性。
```
### 获取SIM卡PIN码剩余次数
#### qosa_sim_get_pin_remain_retries
#### 函数原型
```c
qosa_sim_err_e qosa_sim_get_pin_remain_retries(qosa_uint8_t simid, sim_callback_ptr cb, void *ctx);
```
#### 功能描述
此函数用于异步获取SIM卡PIN码剩余次数。
该操作异步执行，结果通过回调函数返回。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| simid | qosa_uint8_t | 是 | 0~1 | SIM卡ID，用于识别要操作的SIM卡 |
| cb | `sim_callback_ptr` | 是 | 无 | 回调函数指针，用于接收操作结果
回调参数类型：`qosa_sim_get_pin_remain_retries_cnf_t`
操作成功时返回操作成功状态，操作失败时返回错误代码 |
| ctx | void * | 是 | 无 | 用户上下文指针，将在回调时按原样传递 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_INVALID_PARAM`：参数无效
- `QOSA_SIM_ERR_BUSY`: SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为异步操作，实际执行结果通过回调函数返回。
2. 返回的剩余次数信息包括：
- PIN1剩余重试次数
- PUK1剩余重试次数
- PIN2剩余重试次数
- PUK2剩余重试次数
3. 当剩余次数为0时，对应的PIN码将被锁定，需要使用PUK码解锁。
```
### 获取FAC锁状态
#### qosa_sim_get_facility_lock
#### 函数原型
```c
qosa_sim_err_e qosa_sim_get_facility_lock(qosa_uint8_t simid, qosa_uint8_t fac, sim_callback_ptr cb, void *ctx);
```
#### 功能描述
此函数用于异步查询SIM卡上特定功能的当前锁定状态，例如SIM卡锁定、固定拨号锁定等。
该操作异步执行，并通过回调函数返回结果，其中包含指定功能的锁定状态信息。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| simid | qosa_uint8_t | 是 | 0~1 | SIM卡ID，用于识别要查询的SIM卡 |
| fac | qosa_uint8_t | 是 | 无 | 功能类型，请参考 `qosa_sim_facility_e` 枚举定义
常用功能包括：SC（SIM卡锁定）、FD（固定拨号锁定）、P2（PIN2锁定）等
具体支持的功能类型取决于SIM卡和平台的功能 |
| cb | `sim_callback_ptr` | 是 | 无 | 回调函数指针，用于接收操作结果
回调参数类型：`qosa_sim_get_facility_lock_cnf_t`
成功时返回功能锁定状态（0-未激活，1-已激活），失败时返回错误代码 |
| ctx | void * | 是 | 无 | 用户上下文指针，将在回调时按原样传递 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_INVALID_PARAM`：参数无效
- `QOSA_SIM_ERR_BUSY`: SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
- `QOSA_SIM_ERR_OPERATION_NOT_SUPPORTED`: 操作不支持
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为异步操作，实际执行结果通过回调函数返回。
2. 锁定状态返回值：
0：函数未锁定（未激活）
1：函数已锁定（已激活）
3. 设置功能锁定状态前，建议先查询当前状态。
```
### 设置FAC锁
#### qosa_sim_set_facility_lock
#### 函数原型
```c
qosa_sim_err_e qosa_sim_set_facility_lock(
qosa_uint8_t simid,
qosa_sim_facility_e fac,
qosa_sim_pin_t *pin,
qosa_uint8_t mode,
qosa_uint8_t class,
sim_callback_ptr cb,
void *ctx
);
```
#### 功能描述
此功能用于设置或解锁SIM卡上特定功能的锁定状态，例如PIN码锁定、固定拨号锁定等。
支持多种功能类型（设施）和操作模式，操作异步执行，结果通过回调函数返回。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| simid | qosa_uint8_t | 是 | 0~1 | SIM卡ID，用于识别要操作的SIM卡 |
| fac | qosa_uint8_t | 是 | 无 | 功能类型，请参考 `qosa_sim_facility_e` 枚举定义
常用功能包括：SC（SIM卡锁定）、FD（固定拨号锁定）、P2（PIN2锁定）等
具体支持的功能类型取决于SIM卡和平台的功能 |
| pin | `qosa_sim_pin_t` * | 是 | 无 | 指向PIN码结构的指针，其中包含用于验证的PIN码信息
某些功能（例如与PIN2相关的操作）需要提供相应的PIN码
PIN码长度必须在有效范围内（4到8位数字） |
| mode | qosa_uint8_t | 是 | 无 | 操作模式，指定要执行的操作类型
0：解锁功能锁（需要提供正确的PIN码）
1：设置功能锁（需要提供PIN码进行验证） |
| class | qosa_uint8_t | 是 | 无 | 数据类别，指定适用于功能锁的通信类型
1：语音通信
2：数据通信
4：传真通信
7：除短消息外的所有电话通信
8：短消息通信
16：数据线同步通信
32：数据线异步通信
可以使用按位或运算组合多个类别 |
| cb | `sim_callback_ptr` | 是 | 无 | 回调函数指针，用于接收操作结果
回调参数类型：`qosa_sim_general_cnf_t`
成功时返回功能锁定状态（0-未激活，1-已激活），失败时返回错误代码 |
| ctx | void * | 是 | 无 | 用户上下文指针，将在回调时按原样传递 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_INVALID_PARAM`：参数无效
- `QOSA_SIM_ERR_BUSY`: SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
- `QOSA_SIM_ERR_OPERATION_NOT_SUPPORTED`: 操作不支持
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为异步操作，实际执行结果通过回调函数返回。
2. 不同函数类型对 PIN 码的要求可能不同，请参考具体函数的说明。
3. 操作前，建议先查询当前锁定状态。
```
### SIM卡通用接入接口
#### qosa_sim_generic_access
#### 函数原型
```c
qosa_sim_err_e qosa_sim_generic_access(
qosa_uint8_t simid,
qosa_uint8_t *cmd_data,
qosa_uint16_t data_len,
sim_callback_ptr cb,
void *ctx
);
```
#### 功能描述
此函数用于向SIM卡发送原始APDU命令并接收响应，提供最低级别的SIM卡访问能力。
支持发送任何有效的APDU命令，操作异步执行，结果通过回调函数返回。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| simid | qosa_uint8_t | 是 | 0~1 | SIM卡ID，用于识别要操作的SIM卡 |
| cmd_data | qosa_uint8_t * | 是 | 无 | 指向APDU命令数据的指针，其中包含要发送的十六进制数据
数据格式示例：0x00, 0xA4, 0x00, 0x00, 0x02, 0x3F, 0x00（选择主文件）
必须确保数据长度与data_len参数匹配 |
| data_len | qosa_uint16_t | 是 | `QOSA_SIM_C_APDU_LEN_MIN`~`QOSA_SIM_C_APDU_LEN_MAX` | APDU命令数据的实际长度（以字节为单位）
必须在有效范围内：`QOSA_SIM_C_APDU_LEN_MIN` 至 `QOSA_SIM_C_APDU_LEN_MAX` |
| cb | `sim_callback_ptr` | 是 | 无 | 回调函数指针，用于接收操作结果
回调参数类型：`qosa_sim_generic_access_cnf_t`
成功时返回完整的APDU响应（包括状态字），失败时返回错误代码 |
| ctx | void * | 是 | 无 | 用户上下文指针，将在回调时按原样传递 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_INVALID_PARAM`：参数无效
- `QOSA_SIM_ERR_BUSY`: SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
- `QOSA_SIM_ERR_OPERATION_NOT_SUPPORTED`: 操作不支持
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为异步操作，实际执行结果通过回调函数返回。
2. 响应数据包含完整的R-APDU，包括状态字（SW1/SW2）。
3. 使用此接口需要熟悉SIM卡APDU命令格式和规范。
4. 对于标准操作，建议优先使用受限访问接口 (`qosa_sim_restricted_access`)。
```
### SIM卡逻辑通道访问
#### qosa_sim_generic_logical_channel_access
#### 函数原型
```c
qosa_sim_err_e qosa_sim_generic_logical_channel_access(
qosa_uint8_t simid,
qosa_uint32_t session_id,
qosa_uint8_t *cmd_data,
qosa_uint16_t data_len,
sim_callback_ptr cb,
void *ctx
);
```
#### 功能描述
此函数用于向SIM卡发送原始APDU命令并接收响应，提供最低级别的SIM卡访问能力。
支持发送任何有效的APDU命令，操作异步执行，结果通过回调函数返回。
#### 参数说明
| **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** |
| --- | --- | --- | --- | --- |
| simid | qosa_uint8_t | 是 | 0~1 | SIM卡ID，用于识别要操作的SIM卡 |
| session_id | qosa_uint32_t | 是 | 1~`CONFIG_QOSA_SIM_LOGICAL_CHANNEL_NUM` | 逻辑通道会话ID，通过 `qosa_sim_open_logical_channel` 函数获取
取值范围：1至 `CONFIG_QOSA_SIM_LOGICAL_CHANNEL_NUM` |
| cmd_data | qosa_uint8_t * | 是 | 无 | 指向APDU命令数据的指针，其中包含要发送的十六进制数据
数据格式示例：0x00, 0x88, 0x00, 0x81, 0x22, 0x10
必须确保数据长度与data_len参数匹配 |
| data_len | qosa_uint16_t | 是 | `QOSA_SIM_C_APDU_LEN_MIN`~`QOSA_SIM_C_APDU_LEN_MAX` | APDU命令数据的实际长度（以字节为单位）
必须在有效范围内：`QOSA_SIM_C_APDU_LEN_MIN` 至 `QOSA_SIM_C_APDU_LEN_MAX` |
| cb | `sim_callback_ptr` | 是 | 无 | 回调函数指针，用于接收操作结果
回调参数类型：`qosa_sim_generic_logical_channel_access_cnf_t`
成功时返回APDU数据，失败时返回错误代码 |
| ctx | void * | 是 | 无 | 用户上下文指针，将在回调时按原样传递 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_INVALID_PARAM`：参数无效
- `QOSA_SIM_ERR_BUSY`: SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
- `QOSA_SIM_ERR_OPERATION_NOT_SUPPORTED`: 操作不支持
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为异步操作，实际执行结果通过回调函数返回。
2. 使用前，必须先通过 `qosa_sim_open_logical_channel` 成功打开逻辑通道。
3. 响应数据包含完整的R-APDU，包括状态字（SW1/SW2）。
```
### SIM卡限制访问接口
#### qosa_sim_restricted_access
#### 函数原型
```c
qosa_sim_err_e qosa_sim_restricted_access(
qosa_uint8_t simid,
qosa_uint8_t cmd,
qosa_uint16_t fileid,
qosa_uint8_t p1,
qosa_uint8_t p2,
qosa_uint8_t p3,
qosa_sim_cmd_data_t *data,
qosa_sim_path_id_t *path,
sim_callback_ptr cb,
void *ctx
);
```
#### 功能描述
此函数用于对SIM卡执行受限访问操作，支持多种标准SIM卡命令。
受限访问提供了一种标准化的方式来访问SIM卡文件系统，包括读取二进制数据、读取记录、获取响应、更新数据等。
该操作异步执行，结果通过回调函数返回。
#### 参数说明
| **参数名** | **类型** | **范围/单位** | **说明** |
| --- | --- | --- | --- |
| simid | qosa_uint8_t | 0~1 | SIM卡ID，用于识别要操作的SIM卡 |
| cmd | qosa_uint8_t | 无 | 命令代码，请参考 `qosa_sim_restricted_access_command_e` 枚举定义
常用命令包括：`READ_BINARY`、`READ_RECORD`、`GET_RESPONSE`、`UPDATE_BINARY` 等 |
| fileid | qosa_uint16_t | 无 | 文件标识符，指定要访问的SIM卡文件
对于STATUS命令，此参数可以忽略 |
| p1 | qosa_uint8_t | 无 | 命令参数1，具体含义取决于所执行的命令类型
对于除 `GET_RESPONSE` 和 `STATUS` 之外的命令，此参数为必填项 |
| p2 | qosa_uint8_t | 无 | 命令参数2，具体含义取决于所执行的命令类型
对于除 `GET_RESPONSE` 和 `STATUS` 之外的命令，此参数为必填项 |
| p3 | qosa_uint8_t | 无 | 命令参数3通常表示数据长度或偏移量
除 `GET_RESPONSE` 和 `STATUS` 命令外，其他命令均需提供此参数 |
| data | `qosa_sim_cmd_data_t` * | 无 | 指向命令数据结构的指针，该数据结构包含要发送的数据内容
对于写入操作（例如 `UPDATE_BINARY`），此参数不能为NULL。
对于读取操作，此参数通常为NULL |
| path | `qosa_sim_path_id_t` * | 无 | 指向路径标识符结构的指针，用于指定文件访问路径
如果不需要特定路径，可以传入NULL值 |
| cb | `sim_callback_ptr` | 无 | 回调函数指针，用于接收操作结果
回调参数类型：`qosa_sim_restricted_access_cnf_t`
成功时返回操作结果和响应数据，失败时返回错误代码 |
| ctx | void * | 无 | 用户上下文指针，将在回调时按原样传递 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_INVALID_PARAM`：参数无效
- `QOSA_SIM_ERR_BUSY`: SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
- `QOSA_SIM_ERR_OPERATION_NOT_SUPPORTED`: 操作不支持
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为异步操作，实际执行结果通过回调函数返回。
2. 响应数据不包含状态字（SW1/SW2），状态字通过单独的字段返回。
3. 有关具体命令参数的含义，请参阅GSM 11.11规范文档。
```
### 异步获取ICCID
#### qosa_sim_get_iccid
#### 函数原型
```c
qosa_sim_err_e qosa_sim_get_iccid(qosa_uint8_t simid, sim_callback_ptr cb, void *ctx);
```
#### 功能描述
此函数用于异步读取SIM卡的集成电路卡标识符 (ICCID)。
ICCID是SIM卡的唯一标识符，通常印在SIM卡表面，用于识别SIM卡。
此操作异步执行，结果通过回调函数返回。
#### 参数说明
| **参数名** | **类型** | **范围/单位** | **说明** |
| --- | --- | --- | --- |
| simid | qosa_uint8_t | 0~1 | SIM卡ID，用于识别要读取的SIM卡 |
| cb | `sim_callback_ptr` | 无 | 回调函数指针，用于接收操作结果
回调参数类型：`qosa_sim_get_iccid_cnf_t`
成功时返回ICCID字符串，失败时返回错误代码 |
| ctx | void * | 无 | 用户上下文指针，将在回调时按原样传递 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_BUSY`: SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
- `QOSA_SIM_ERR_FAILURE`: 获取失败
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为异步操作，实际执行结果通过回调函数返回。
2. ICCID通常为19-20位数字字符串，格式为：MMCC IINN NNNN NNNN NN C
```
### 同步获取ICCID
#### qosa_sim_read_iccid
#### 函数原型
```c
qosa_sim_err_e qosa_sim_read_iccid(qosa_uint8_t simid, qosa_sim_iccid_t *iccid);
```
#### 功能描述
此函数用于同步读取SIM卡的集成电路卡标识符 (ICCID)。
ICCID是SIM卡的唯一标识符，通常印在SIM卡表面，用于识别SIM卡。
此函数将直接返回读取结果，适用于需要立即获取ICCID的场景。
#### 参数说明
| **参数名** | **类型** | **范围/单位** | **说明** |
| --- | --- | --- | --- |
| simid | qosa_uint8_t | 0~1 | SIM卡ID，用于识别要读取的SIM卡 |
| iccid | `qosa_sim_iccid_t` * | 无 | 指向ICCID结构的指针，用于接收读取的ICCID信息
ICCID以字符串格式存储在该结构中
调用者需要确保传入有效的指针 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_BUSY`: SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
- `QOSA_SIM_ERR_FAILURE`: 获取失败
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为同步操作，会阻塞当前线程直至操作完成。
2. ICCID通常为19-20位数字字符串，格式为：MMCC IINN NNNN NNNN NN C
```
### 打开一个逻辑通道
#### qosa_sim_open_logical_channel
#### 函数原型
```c
qosa_sim_err_e qosa_sim_open_logical_channel(qosa_uint8_t simid, qosa_sim_dfname_t *dfname, sim_callback_ptr cb, void *ctx);
```
#### 功能描述
此函数用于在SIM卡上打开一个新的逻辑通道，以便通过该通道与特定应用程序通信。
逻辑通道允许与SIM卡上的多个应用程序同时通信，每个通道独立工作。
打开操作异步执行，结果通过回调函数返回。
#### 参数说明
| **参数名** | **类型** | **范围/单位** | **说明** |
| --- | --- | --- | --- |
| simid | qosa_uint8_t | 0~1 | SIM卡ID，用于识别要读取的SIM卡 |
| dfname | `qosa_sim_dfname_t` * | 无 | 指向DF名称结构的指针，其中包含要访问的应用程序标识符 (AID)
AID用于标识SIM卡上的特定应用程序
AID长度必须在有效范围内（1到 `QOSA_SIM_AID_LEN_MAX` 字节） |
| cb | `sim_callback_ptr` | 无 | 回调函数指针，用于接收操作结果
回调参数类型：`qosa_sim_open_logical_channel_cnf_t`
成功时返回逻辑通道会话ID，失败时返回错误代码 |
| ctx | void * | 无 | 用户上下文指针，将在回调时按原样传递 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_INVALID_PARAM`: 参数无效
- `QOSA_SIM_ERR_BUSY`: SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
- `QOSA_SIM_ERR_OPERATION_NOT_SUPPORTED`: 操作失败
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为异步操作，实际执行结果通过回调函数返回。
2. 已打开的逻辑通道必须在使用后通过 `qosa_sim_close_logical_channel` 关闭。
3. 逻辑通道的数量受平台限制 (`CONFIG_QOSA_SIM_LOGICAL_CHANNEL_NUM`)。
```
### 关闭一个逻辑通道
#### qosa_sim_close_logical_channel
#### 函数原型
```c
qosa_sim_err_e qosa_sim_close_logical_channel(qosa_uint8_t simid, qosa_uint32_t sessionid, sim_callback_ptr cb, void *ctx);
```
#### 功能描述
此函数用于关闭之前通过 `qosa_sim_open_logical_channel` 打开的SIM卡逻辑通道。
关闭操作异步执行，结果通过回调函数返回。
#### 参数说明
| **参数名** | **类型** | **范围/单位** | **说明** |
| --- | --- | --- | --- |
| simid | qosa_uint8_t | 0~1 | SIM卡ID，用于识别要读取的SIM卡 |
| sessionid | qosa_uint32_t | 1~`CONFIG_QOSA_SIM_LOGICAL_CHANNEL_NUM` | 逻辑通道会话ID，通过 `qosa_sim_open_logical_channel` 函数获取
取值范围：1至 `CONFIG_QOSA_SIM_LOGICAL_CHANNEL_NUM` |
| cb | `sim_callback_ptr` | 无 | 回调函数指针，用于接收操作结果
回调参数类型：`qosa_sim_general_cnf_t` |
| ctx | void * | 无 | 用户上下文指针，将在回调时按原样传递 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_INVALID_PARAM`: 参数无效
- `QOSA_SIM_ERR_BUSY`: SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
详见 `qosa_sim_err_e`。
```{note}
**注意：**
1. 此函数为异步操作，实际执行结果通过回调函数返回。
2. 关闭不存在的逻辑通道将返回错误。
```
### 获取SIM卡里的电话号码
#### qosa_sim_get_phonenumber
#### 函数原型
```c
qosa_sim_err_e qosa_sim_get_phonenumber(qosa_uint8_t simid, qosa_sim_phonenumber_t *phonenumber);
```
#### 功能描述
此功能用于读取存储在SIM卡中的本地电话号码信息，包括号码内容和类型信息。
支持读取多个电话号码（最多4个），每个号码包含号码内容和地址类型信息。
#### 参数说明
| **参数名** | **类型** | **范围/单位** | **说明** |
| --- | --- | --- | --- |
| simid | qosa_uint8_t | 0~1 | SIM卡ID，用于识别要读取的SIM卡 |
| phonenumber | `qosa_sim_phonenumber_t` * | 无 | 指向电话号码结构的指针，用于接收读取的电话号码信息
包含号码数量、号码列表（号码内容和类型信息）
类型信息包括：129-未知类型（ISDN格式），145-国际号码（ISDN格式），161-国内号码等 |
#### 返回值说明
- `QOSA_SIM_ERR_OK`：操作成功
- `QOSA_SIM_ERR_INVALID_PARAM`: 参数无效
- `QOSA_SIM_ERR_BUSY`: SIM卡繁忙
- `QOSA_SIM_ERR_NOT_INSERTED`: SIM卡未插入
详见 `qosa_sim_err_e`。
## 数据结构定义
### qosa_modem_general_cnf_t结构体定义
```cpp
/** osa modem api cnf return result structure common parameters, the first two parameters of each cnf structure must be this */
#define QOSA_MODEM_COMMON_CNF_HDR \
qosa_uint8_t simid; /*!< sim id */ \
qosa_uint32_t err_code /*!< error code, success is OSA_OK, failure is others, when this value indicates failure, application layer is not allowed to parse other parameters */
/**
* @struct qosa_modem_general_cnf_t
* @brief Modem cnf general reply, used to return simple error and execution success reply.
*
*/
typedef struct
{
QOSA_MODEM_COMMON_CNF_HDR;
} qosa_modem_general_cnf_t;
```
### qosa_sim_general_cnf_t结构体定义
```cpp
/**
* @struct qosa_sim_general_cnf_t
* @brief SIM card general result return, used to return simple success or failure, no additional result return type
*
*/
typedef qosa_modem_general_cnf_t qosa_sim_general_cnf_t;
```
### qosa_sim_get_imsi_cnf_t结构体定义
```cpp
/**
* @struct qosa_sim_get_imsi_cnf_t
* @brief the result of qosa_sim_get_imsi API
*
*/
typedef struct sim_get_imsi_cnf
{
QOSA_MODEM_COMMON_CNF_HDR; /*!< common header, simid and err_code */
qosa_sim_imsi_t imsi; /*!< imsi data, in string format */
} qosa_sim_get_imsi_cnf_t;
```
### qosa_sim_get_iccid_cnf_t结构体定义
```cpp
/**
* @struct qosa_sim_get_iccid_cnf_t
* @brief the result of qosa_sim_get_iccid API
*
*/
typedef struct sim_get_iccid_cnf
{
QOSA_MODEM_COMMON_CNF_HDR; /*!< common header, simid and err_code */
qosa_sim_iccid_t iccid; /*!< iccid in string format */
} qosa_sim_get_iccid_cnf_t;
```
### qosa_sim_get_status_cnf_t结构体定义
```c
/**
* @struct qosa_sim_get_status_cnf_t
* @brief the result of qosa_sim_get_status API
*
*/
typedef struct sim_get_status_cnf
{
QOSA_MODEM_COMMON_CNF_HDR; /*!< common header, simid and err_code */
qosa_sim_status_e status; /*!< sim status */
} qosa_sim_get_status_cnf_t;
```
### qosa_sim_generic_access_cnf_t结构体定义
```cpp
/**
* @struct qosa_sim_generic_access_cnf_t
* @brief the result of qosa_sim_generic_access API
*
*/
typedef struct sim_generic_access_cnf
{
QOSA_MODEM_COMMON_CNF_HDR; /*!< common header, simid and err_code */
qosa_uint16_t data_len; /*!< the length of data */
qosa_uint8_t data[QOSA_SIM_R_APDU_LEN_MAX + 1]; /*!< response APDU, include sw */
} qosa_sim_generic_access_cnf_t;
```
### qosa_sim_generic_logical_channel_access_cnf_t结构体定义
```cpp
/**
* @struct qosa_sim_generic_logical_channel_access_cnf_t
* @brief the result of qosa_sim_generic_logical_channel_access API
*
*/
typedef struct sim_generic_logical_channel_access_cnf
{
QOSA_MODEM_COMMON_CNF_HDR; /*!< common header, simid and err_code */
qosa_uint16_t data_len; /*!< the length of data */
qosa_uint8_t data[QOSA_SIM_R_APDU_LEN_MAX + 1]; /*!< response APDU, include sw */
} qosa_sim_generic_logical_channel_access_cnf_t;
```
### qosa_sim_restricted_access_cnf_t结构体定义
```cpp
/**
* @struct qosa_sim_restricted_access_cnf_t
* @brief the result of qosa_sim_restricted_access API
*
*/
typedef struct sim_restricted_access_cnf
{
QOSA_MODEM_COMMON_CNF_HDR; /*!< common header, simid and err_code */
qosa_uint8_t sw1; /*!< sw1 */
qosa_uint8_t sw2; /*!< sw2 */
qosa_uint16_t data_len; /*!< the length of data */
qosa_uint8_t data[QOSA_SIM_R_APDU_DATA_LEN_MAX + 1]; /*!< response APDU data field, not include sw */
} qosa_sim_restricted_access_cnf_t;
```
### qosa_sim_open_logical_channel_cnf_t结构体定义
```cpp
/**
* @struct qosa_sim_open_logical_channel_cnf_t
* @brief the result of qosa_sim_open_logical_channel API
*
*/
typedef struct sim_open_logical_channel_cnf
{
QOSA_MODEM_COMMON_CNF_HDR; /*!< common header, simid and err_code */
qosa_uint32_t channel_session; /*!< link between the card and the external world during a card session on a given logical channel */
} qosa_sim_open_logical_channel_cnf_t;
```
### qosa_sim_get_pin_remain_retries_cnf_t结构体定义
```cpp
/**
* @struct osa_sim_pin_remain_retries_cnf_t
* @brief the result of qosa_sim_get_pin_remain_retries API
*
*/
typedef struct sim_pin_remain_retries_cnf
{
QOSA_MODEM_COMMON_CNF_HDR; /*!< common header, simid and err_code */
qosa_uint8_t pin1_remain; /*!< PIN1 remain retry counts */
qosa_uint8_t puk1_remain; /*!< PUK1 remain retry counts */
qosa_uint8_t pin2_remain; /*!< PIN2 remain retry counts */
qosa_uint8_t puk2_remain; /*!< PUK2 remain retry counts */
} qosa_sim_get_pin_remain_retries_cnf_t;
```
### qosa_sim_get_facility_lock_cnf_t结构体定义
```cpp
/**
* @struct qosa_sim_get_facility_lock_cnf_t
* @brief the result of qosa_sim_get_facility_lock API
*
*/
typedef struct sim_get_facility_lock_cnf
{
QOSA_MODEM_COMMON_CNF_HDR; /*!< common header, simid and err_code */
qosa_uint8_t status; /*!< 0:not active 1:active */
} qosa_sim_get_facility_lock_cnf_t;
```
### qosa_sim_get_file_update_count_cnf_t结构体定义
```cpp
/**
* @struct qosa_sim_get_file_update_count_cnf_t
* @brief the result of qosa_sim_get_file_update_count API
*
*/
typedef struct sim_get_file_update_count_cnf
{
QOSA_MODEM_COMMON_CNF_HDR; /*!< common header, simid and err_code */
qosa_sim_ef_info_t ef_info[QOSA_SIM_WRITE_SIM_FILE_COUNT_MAX]; /*!< response EF info */
} qosa_sim_get_file_update_count_cnf_t;
```
### qosa_sim_pin_t结构体定义
```cpp
/**
* @struct qosa_sim_pin_t
* @brief PIN code
*
*/
typedef struct sim_pin
{
qosa_uint8_t length; /*!< pin code data length */
qosa_uint8_t pin_data[QOSA_SIM_PIN_LEN_MAX + 1]; /*!< pin code data, max to QOSA_SIM_PIN_LEN_MAX */
} qosa_sim_pin_t;
```
### qosa_sim_iccid_t结构体定义
```cpp
/**
* @struct qosa_sim_iccid_t
* @brief type for iccid
*
*/
typedef struct
{
char id[QOSA_SIM_ICCID_LEN + 1]; /*!< iccid, in string format */
} qosa_sim_iccid_t;
```
### qosa_sim_imsi_t结构体定义
```cpp
/**
* @struct qosa_sim_imsi_t
* @brief type for imsi
*
*/
typedef struct
{
char imsi[QOSA_SIM_IMSI_LEN_MAX + 1]; /*!< imsi, in string format */
} qosa_sim_imsi_t;
```
### qosa_sim_dfname_t结构体定义
```cpp
/**
* @struct qosa_sim_dfname_t
* @brief dfname is the Application Identifier
*
*/
typedef struct
{
qosa_uint8_t length; /*!< the length of aid */
qosa_uint8_t aid[QOSA_SIM_AID_LEN_MAX + 1]; /*!< aid, hexadecimal data*/
} qosa_sim_dfname_t;
```
### qosa_sim_hot_swap_cfg_t结构体定义
```cpp
/**
* @struct qosa_sim_hot_swap_cfg_t
* @brief Used to configure the hot swap function of SIM card, including whether to enable hot swap detection, the detection pin level when SIM card is inserted, and the GPIO pin used for hot swap detection (optional).
*
*/
typedef struct sim_hot_swap_cfg
{
qosa_bool_t enable; /*!< Whether to enable SIM card hot swap detection */
qosa_sim_insert_level_e insert_level; /*!< Detection pin detection level when SIM card is inserted */
qosa_uint32_t gpio; /*!< to be implemented, configured as QOSA_SIM_HOT_SWAP_UNSPECIFIED_GPIO means using product default configuration pins */
} qosa_sim_hot_swap_cfg_t;
```
### qosa_sim_cmd_data_t结构体定义
```cpp
/**
* @struct qosa_sim_cmd_data_t
* @brief command APDU data field
*
*/
typedef struct sim_cmd_data
{
qosa_uint8_t length; /*!< the length of command APDU data field */
qosa_uint8_t cmd_data[QOSA_SIM_C_APDU_DATA_LEN_MAX]; /*!< command APDU data field */
} qosa_sim_cmd_data_t;
```
### qosa_sim_path_id_t结构体定义
```cpp
/**
* @struct qosa_sim_path_id_t
* @brief sim path id
*
*/
typedef struct sim_path_id
{
qosa_uint8_t length; /*!< the length of path id */
qosa_uint8_t path_id_data[QOSA_SIM_PATH_ID_LEN_MAX]; /*!< path id data */
} qosa_sim_path_id_t;
```
### qosa_sim_phonenumber_data_t结构体定义
```cpp
/**
* @struct qosa_sim_phonenumber_data_t
* @brief SIM card phone number content.
*
*/
typedef struct sim_phone_number_data
{
qosa_uint8_t type; /*!< Eight-bit byte address type, e.g.: 129-unknown type (ISDN format), 145-international number (ISDN format), 161-national number*/
char phone_number[QOSA_SIM_PHONENUMBER_MAX_LEN]; /*!< Content of the number */
} qosa_sim_phonenumber_data_t;
```
## 枚举类型定义
### qosa_sim_err_e枚举定义
```thrift
/**
* @enum qosa_sim_err_e
* @brief SIM error codes
*
*/
typedef enum sim_err
{
QOSA_SIM_ERR_OK = 0,
QOSA_SIM_ERR_OPERATION_NOT_ALLOWED = 3 | QOSA_ERRCODE_SIM_BASE, /*!< operation not allowed */
QOSA_SIM_ERR_OPERATION_NOT_SUPPORTED = 4 | QOSA_ERRCODE_SIM_BASE, /*!< operation not supported */
QOSA_SIM_ERR_NOT_INSERTED = 10 | QOSA_ERRCODE_SIM_BASE, /*!< SIM not inserted */
QOSA_SIM_ERR_PUK_REQUIRED = 12 | QOSA_ERRCODE_SIM_BASE, /*!< SIM PUK required */
QOSA_SIM_ERR_FAILURE = 13 | QOSA_ERRCODE_SIM_BASE, /*!< SIM failure */
QOSA_SIM_ERR_BUSY = 14 | QOSA_ERRCODE_SIM_BASE, /*!< SIM busy */
QOSA_SIM_ERR_WRONG = 15 | QOSA_ERRCODE_SIM_BASE, /*!< SIM wrong */
QOSA_SIM_ERR_INCORRECT_PASSWORD = 16 | QOSA_ERRCODE_SIM_BASE, /*!< incorrect password */
QOSA_SIM_ERR_PIN2_REQUIRED = 17 | QOSA_ERRCODE_SIM_BASE, /*!< SIM PIN2 required */
QOSA_SIM_ERR_PUK2_REQUIRED = 18 | QOSA_ERRCODE_SIM_BASE, /*!< SIM PUK2 required */
QOSA_SIM_ERR_MEMORY_FULL = 20 | QOSA_ERRCODE_SIM_BASE, /*!< memory full */
QOSA_SIM_ERR_NOT_FOUND = 22 | QOSA_ERRCODE_SIM_BASE, /*!< not found */
QOSA_SIM_ERR_MEMORY_FAILURE = 23 | QOSA_ERRCODE_SIM_BASE, /*!< memory failure */
QOSA_SIM_ERR_INVALID_PARAM = 53 | QOSA_ERRCODE_SIM_BASE, /*!< invalid parameter */
QOSA_SIM_ERR_EXECUTE = 1 | (QOSA_ERRCODE_SIM_BASE + QOSA_AT_ERR_OFS),
} qosa_sim_err_e;
```
### qosa_sim_type_e枚举定义
```thrift
/**
* @enum qosa_sim_type_e
* @brief OSA SIM types
*
*/
typedef enum sim_type
{
QOSA_SIM_TYPE_INVALID = -1, /*!< Invalid SIM type */
QOSA_SIM, /*!< Subscriber Identity Module */
QOSA_USIM, /*!< Universal Subscriber Identity Module */
} qosa_sim_type_e;
```
### qosa_sim_status_e枚举定义
```sql
/**
* @enum qosa_sim_status_e
* @brief SIM card status definitions
*
*/
typedef enum sim_status
{
QOSA_SIM_STATUS_READY, /*!< MT is not pending for any password */
QOSA_SIM_STATUS_SIM_PIN, /*!< MT waiting SIM PIN to be given */
QOSA_SIM_STATUS_SIM_PUK, /*!< MT waiting SIM PUK to be given */
QOSA_SIM_STATUS_PHONE_TO_SIM_PIN, /*!< MT is waiting phone-to-SIM card password to be given */
QOSA_SIM_STATUS_PHONE_TO_FIRST_SIM_PIN, /*!< MT is waiting phone-to-very first SIM card password to be given */
QOSA_SIM_STATUS_PHONE_TO_FIRST_SIM_PUK, /*!< MT is waiting phone-to-very first SIM card unblocking password to be given */
QOSA_SIM_STATUS_SIM_PIN2, /*!< MT is waiting SIM PIN2 to be given */
QOSA_SIM_STATUS_SIM_PUK2, /*!< MT is waiting SIM PUK2 to be given */
QOSA_SIM_STATUS_NETWORK_PIN, /*!< MT is waiting network personalization password to be given */
QOSA_SIM_STATUS_NETWORK_PUK, /*!< MT is waiting network personalization unblocking password to be given */
QOSA_SIM_STATUS_NETWORK_SUBSET_PIN, /*!< MT is waiting network subset personalization password to be given */
QOSA_SIM_STATUS_NETWORK_SUBSET_PUK, /*!< MT is waiting network subset personalization unblocking password to be given */
QOSA_SIM_STATUS_SERVICE_PROVIDER_PIN, /*!< MT is waiting service provider personalization password to be given */
QOSA_SIM_STATUS_SERVICE_PROVIDER_PUK, /*!< MT is waiting service provider personalization unblocking password to be given */
QOSA_SIM_STATUS_CORPORATE_PIN, /*!< MT is waiting corporate personalization password to be given */
QOSA_SIM_STATUS_CORPORATE_PUK, /*!< MT is waiting corporate personalization unblocking password to be given */
QOSA_SIM_STATUS_NOT_INSERTED, /*!< SIM card is not inserted */
QOSA_SIM_STATUS_BUSY, /*!< SIM busy */
QOSA_SIM_STATUS_BLOCKED, /*!< SIM blocked */
QOSA_SIM_STATUS_UNKNOWN, /*!< unknown status */
QOSA_SIM_STATUS_ESIM_NO_PROFILE, /*!< eSIM has no profile */
} qosa_sim_status_e;
```
### qosa_sim_facility_e枚举定义
```thrift
/**
* @enum qosa_sim_facility_e
* @brief Enumerates the facility lock types for SIM cards
*
*/
typedef enum sim_facility
{
QOSA_SIM_FACILITY_AB, /*!< all barring service */
QOSA_SIM_FACILITY_AC, /*!< all incoming barring services */
QOSA_SIM_FACILITY_FD, /*!< SIM card or active application in the UICC (GSM or USIM) fixed dialling memory feature (if PIN2 authentication has not been done during the current session, PIN2 is required as )*/
QOSA_SIM_FACILITY_AG, /*!< all outing barring services */
QOSA_SIM_FACILITY_AI, /*!< barr all incoming calls */
QOSA_SIM_FACILITY_AO, /*!< barr all outgoing calls */
QOSA_SIM_FACILITY_IR, /*!< barr incoming calls when roaming outside the nome country */
QOSA_SIM_FACILITY_OI, /*!< barr outgoing international calls */
QOSA_SIM_FACILITY_OX, /*!< barr outgoing international calls except to home country */
QOSA_SIM_FACILITY_SC, /*!< lock SIM/UICC CARD INSTALLED in the currently selected card slot */
QOSA_SIM_FACILITY_P2, /*!< sim pin2 */
} qosa_sim_facility_e;
```
### qosa_sim_restricted_access_command_e枚举定义
```thrift
/**
* @enum qosa_sim_restricted_access_command_e
* @brief Enumerates instruction codes for command APDU
*
* This enumeration defines various command codes used to perform restricted access operations with the SIM card.
*/
typedef enum sim_restricted_access_command
{
QOSA_SIM_READ_BINARY = 176, /*!< Reads a string of bytes from the current transparent EF */
QOSA_SIM_READ_RECORD = 178, /*!< Reads one complete record in the current linear fixed or cyclic EF */
QOSA_SIM_GET_RESPONSE = 192, /*!< Retrieves response data from the SIM card */
QOSA_SIM_UPDATE_BINARY = 214, /*!< Updates the current transparent EF with a string of bytes */
QOSA_SIM_UPDATE_RECORD = 220, /*!< Updates one specific, complete record in the current linear fixed or cyclic EF */
QOSA_SIM_STATUS = 242, /*!< Retrieves information about the current directory or current application */
} qosa_sim_restricted_access_command_e;
```
### qosa_sim_insert_stat_e枚举定义
```java
/**
* @enum qosa_sim_insert_stat_e
* @brief SIM card insertion status
*
*/
typedef enum
{
QOSA_SIM_INSERT_STAT_REMOVED = 0, /*!< SIM card is not inserted */
QOSA_SIM_INSERT_STAT_INSERTED = 1, /*!< SIM card insertion status */
QOSA_SIM_INSERT_STAT_UNKNOWN = 2, /*!< SIM card status unknown */
} qosa_sim_insert_stat_e;
```
# 应用示例
### 检查SIM状态
请查看 https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/network/sim/sim_status.c
### 获取ICCID
请查看 https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/network/sim/sim_iccid.c
### 获取IMSI
请查看 https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/network/sim/sim_imsi.c
### 设置热插拔
请查看 https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/network/sim/sim_hot_swap.c
### 双卡单待，切换卡槽
请查看 https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/network/sim/sim_dual.c