# eSIM ***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.*** --- ## 概述 eSIM（embedded SIM）是一种将传统SIM卡功能做成嵌入式芯片、并通过远程方式下载运营商Profile的技术。它遵循GSMA全球统一标准，无需实体卡槽，终端出厂即可“空中激活”，实现灵活选网、秒级开户。eSIM节省卡槽空间、降低物流与库存成本，同时支持多运营商Profile本地切换，广泛应用于智能手机、可穿戴、车载、物联网等领域，是设备“无卡化”与全球连接的核心底座。 ### eSIM功能介绍（基于SIM安全要素与API模块） eSIM（嵌入式SIM）在继承传统SIM卡五大安全要素（ICCID、IMSI、Ki、文件系统、PIN/PUK）的基础上，通过远程配置与本地安全隔离机制，实现了Profile全生命周期管理。其核心功能模块如下： 1. Profile本地管理 管理eSIM中的Profile，包括激活、去激活与删除操作。 2. Profile空中下载（OTA） 通过HTTPS网络协议完成Profile远程下载。 3. 通知管理 上报Profile状态变更（如激活、去激活与删除）至SM-DP+平台。 4. eIM本地管理 管理eSIM中的eIM（eSIM Identity Manager），包括添加和重置。 5. IPA逻辑管理 配置IPA（IoT Profile Assistant）逻辑，控制IPA和eIM的交互。 6. Fallback功能 当使用中的Profile失去注网能力时，自动/手动回退至预设紧急Profile，保障基础通信能力不中断。 7. eSIM SDK基本信息查询 提供标准API接口，供终端应用查询当前eSIM SDK的版本信息和编译信息等。 # API说明 ## 头文件 `esim_interface.h` ## 函数列表
函数 说明 备注
esim_intf_server_start() 在SDK中启用并初始化IPA功能  
esim_intf_server_stop() 在SDK中停用并释放IPA功能  
esim_intf_get_operational_profile() 获取operational类型的Profile  
esim_intf_get_all_profile() 获取所有Profile  
esim_intf_eid_get() 获取EID十六进制字符串  
esim_intf_ver_get() 获取eSIM SDK版本信息  
esim_intf_compile_data_get() 获取eSIM SDK编译日期  
esim_intf_direct_download_profile() 使用激活码和确认码直接下载配置文件 使用模组内部网络下载Profile
esim_intf_indirect_download_profile_start() 使用激活码和确认码启动间接下载Profile流程 使用模组外部网络下载Profile
esim_intf_indirect_download_data_transfer() 传输Profile间接下载流程中DP+返回的数据给模组
esim_intf_poll_interval_set() 设置IPA轮询间隔时间  
esim_intf_ipa_time_cfg_get() 获取IPA轮询间隔时间和Rollback时间  
esim_intf_eim_info_get() 获取eIM信息列表  
esim_intf_initail_eim_add() 添加首个eIM信息  
esim_intf_fallback_exte() 执行Fallback操作  
esim_intf_fallback_return_exte() 执行Fallback return操作  
esim_intf_euicc_memory_reset() 重置eUICC内存  
esim_intf_ipa_pll_delay_get() 获取轮询延时时间  
esim_intf_ipa_pll_delay_set() 设置轮询延时时间  
esim_intf_notification_list() 遍历eUICC中的通知信息  
esim_intf_notification_remove() 从待办通知列表中删除此类通知  
esim_intf_retrieve_notification_by_seq() 根据序列号检索通知完整数据  
esim_intf_report_notification_by_seq() 根据序列号检索通知，然后上报给服务器并删除通知  
esim_intf_profile_handle() Profile启用/禁用/删除操作  
esim_intf_profile_nickname_set() 根据ICCID修改指定用户资料的昵称信息  
## 函数定义 ### 初始化eSIM服务 #### esim_intf_server_start #### 函数原型 ```c int esim_intf_server_start(void); ``` #### 功能描述 此功能用于初始化eSIM服务，主要包含创建eSIM线程，配置eSIM功能初始参数等。 #### 参数说明 无 #### 返回值说明 - `0`：初始化成功 - `other`：失败 ### 停用并释放eSIM服务 #### esim_intf_server_stop #### 函数原型 ```c int esim_intf_server_stop(void); ``` #### 功能描述 此功能用于停止eSIM服务，删除eSIM线程，并释放相应资源。 #### 参数说明 无 #### 返回值说明 - `0`：初始化成功 - `other`：失败 ### 获取operational类型的Profile #### esim_intf_get_operational_profile #### 函数原型 ```c esim_result_errno_e esim_intf_get_operational_profile(qosa_q_type_t *profile_list); ``` #### 功能描述 此功能用于获取eUICC中operational类型的Profile信息。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | profile_list | `qosa_q_type_t` * | 是 | 无 | 存储Profile的链表，使用前须完成初始化
节点类型 `esim_profile_info_t` | #### 返回值说明 - `ESIM_OK`：获取Profile成功 - `其他`：获取失败 详见 `esim_result_errno_e`。 ### 获取全部的Profile #### esim_intf_get_all_profile #### 函数原型 ```c esim_result_errno_e esim_intf_get_all_profile(qosa_q_type_t *profile_list); ``` #### 功能描述 此功能用于获取eUICC中全部的Profile信息。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | profile_list | `qosa_q_type_t` * | 是 | 无 | 存储Profile的链表，使用前须完成初始化
节点类型 `esim_profile_info_t` | #### 返回值说明 - `ESIM_OK`：获取Profile成功 - `其他`：获取失败 详见 `esim_result_errno_e`。 ### 获取EID #### esim_intf_eid_get #### 函数原型 ```c esim_result_errno_e esim_intf_eid_get(char *eid); ``` #### 功能描述 此功能用于获取eUICC的ID。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | eid | char * | 是 | 无 | EID长度为32个字节，eid的大小应大于32字节 | #### 返回值说明 - `ESIM_OK`：获取EID成功 - `其他`：获取失败 详见 `esim_result_errno_e`。 ### 获取eSIM SDK版本号 #### esim_intf_ver_get #### 函数原型 ```c int esim_intf_ver_get(char *ver_buf, int ver_buf_size); ``` #### 功能描述 此功能用于获取eSIM SDK版本号, 例如"eSIM_IPA_v1.9.0"。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | ver_buf | char * | 是 | 无 | 用于存放eSIM SDK版本号数据（ver_buf空间大小应大于32字节） | | ver_buf_size | int | 是 | 大于32 | ver_buf的大小 | #### 返回值说明 - `大于0`：获取版本号成功，返回版本号字符长度 - `0`：获取失败 ### 获取eSIM SDK版本时间 #### esim_intf_compile_data_get #### 函数原型 ```c int esim_intf_compile_data_get(char *cmp_buf, int cmp_buf_size); ``` #### 功能描述 此功能用于获取eSIM SDK版本时间，例如"20260101"。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | cmp_buf | char * | 是 | 无 | 用于存放eSIM SDK版本时间数据（cmp_buf大小应大于16字节） | | cmp_buf_size | int | 是 | 大于16 | cmp_buf的大小 | #### 返回值说明 - `大于0`：获取版本时间成功，返回版本号字符长度 - `0`：获取失败 ### 内部网络下载Profile #### esim_intf_direct_download_profile #### 函数原型 ```c esim_result_errno_e esim_intf_direct_download_profile( char *ac_code, int ac_len, char *cfmt_code, int cfmt_len, esim_data_array_t *iccid_str); ``` #### 功能描述 此功能用于使用模组的网络下载Profile，需要模组网络质量良好，此功能会和SM-DP+服务器做四次交互，耗时较长。 此操作需确保模组网络正常，无占用。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | ac_code | char * | 是 | 无 | 激活码 | | ac_len | int | 是 | 无 | 激活码长度 | | cfmt_code | char * | 是 | 无 | 确认码（若不需要确认码，设置 `NULL`） | | cfmt_len | int | 是 | 无 | 确认码长度（若不需要确认码，设置0） | | iccid_str | `esim_data_array_t` * | 是 | 无 | Profile下载成功时，用于存放Profile的ICCID数据 | #### 返回值说明 - `ESIM_OK`：Profile下载成功 - `其他`：获取失败 详见 `esim_result_errno_e`。 ### 启动外部网络下载Profile #### esim_intf_indirect_download_profile_start #### 函数原型 ```c esim_smdpp_indirect_result_t *esim_intf_indirect_download_profile_start( char *ac_code, int ac_len, char *cfmt_code, int cfmt_len); ``` #### 功能描述 此功能用于启动使用模组外部网络下载Profile的流程，后续需要配合 `esim_intf_indirect_download_data_transfer()` 接口实现Profile完整下载。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | ac_code | char * | 是 | 无 | 激活码 | | ac_len | int | 是 | 无 | 激活码长度 | | cfmt_code | char * | 是 | 无 | 确认码（若不需要确认码，设置 `NULL`） | | cfmt_len | int | 是 | 无 | 确认码长度（若不需要确认码，设置0） | #### 返回值说明 返回数据是需要转发给SM-DP+的请求参数 - `成员ret为ESIM_OK`：流程启动成功 - `成员ret不为ESIM_OK`：流程启动失败，需要重新发起流程 - `成员end_flag为TRUE`：流程启动失败，需要重新发起流程 - `空指针`：流程启动失败，需要重新发起流程 详见 `esim_smdpp_indirect_result_t`。 ### 外部网络下载Profile数据传输 #### esim_intf_indirect_download_data_transfer #### 函数原型 ```c esim_smdpp_indirect_result_t *esim_intf_indirect_download_data_transfer( qosa_bool_t state, qosa_uint8_t seq, qosa_uint8_t *data, qosa_uint32_t data_len); ``` #### 功能描述 此功能用于在使用模组外部网络下载Profile的流程传输SM-DP+返回的数据给模组，支持数据分包传输。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | state | qosa_bool_t | 是 | 无 | 数据包状态，
`QOSA_TRUE` 表示非最后一包数据
`QOSA_FALSE` 表示最后一包数据 | | seq | qosa_uint8_t | 是 | 大于0 | 分包序列号
seq必须从0开始，标识起始数据包
后续每个数据包的seq必须按序递增1，不允许出现乱序 | | data | qosa_uint8_t * | 是 | 无 | 分包数据，转换成十六进制字符串的数据 | | data_len | qosa_uint32_t | 是 | 无 | 分包数据长度,必须是偶数 | #### 返回值说明 返回数据是需要转发给SM-DP+的请求参数 - `成员ret为ESIM_OK`：流程启动成功 - `成员ret不为ESIM_OK`：流程启动失败，需要重新发起流程 - `成员end_flag为TRUE`：流程结束，需通过ret判断profile安装结果 - `空指针`：流程启动失败，需要重新发起流程 详见 `esim_smdpp_indirect_result_t`。 ### 设置IPA轮询 #### esim_intf_poll_interval_set #### 函数原型 ```c esim_result_errno_e esim_intf_poll_interval_set(qosa_uint32_t *sec); ``` #### 功能描述 此功能用于控制IPA对eIM的请求时机，既可以设置定期请求的间隔，也可以随时发起一次立即请求。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | sec | `qosa_uint32_t` * | 是 | 无 | sec不为 `NULL` 时，设置定期请求的间隔
单位 秒，取值范围 [0, 120~3888000]
设置为0时，停止定期请求
sec为 `NULL` 立即发起一次请求 | #### 返回值说明 - `ESIM_OK`：轮询设置成功 - `其他`：轮询设置失败 详见 `esim_result_errno_e`。 ### 查询IPA轮询间隔与rollback时限 #### esim_intf_ipa_time_cfg_get #### 函数原型 ```c esim_result_errno_e esim_intf_ipa_time_cfg_get(esim_ipa_timer_cfg_t *time_cfg); ``` #### 功能描述 此功能用于查询IPA设置定期请求的间隔和rollback的自动触发时间限制 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | time_cfg | `esim_ipa_timer_cfg_t` * | 是 | 无 | 用于存储IPA轮询间隔与rollback时限
详见 `esim_ipa_timer_cfg_t` | #### 返回值说明 - `ESIM_OK`：查询成功 - `其他`：查询失败 详见 `esim_result_errno_e`。 ### 查询eIM信息 #### esim_intf_eim_info_get #### 函数原型 ```c esim_result_errno_e esim_intf_eim_info_get(qosa_q_type_t *eim_info_list); ``` #### 功能描述 此功能用于获取eUICC中全部的eIM信息。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | eim_info_list | `qosa_q_type_t` * | 是 | 无 | 存储eIM的链表，使用前须完成初始化
节点类型 `esim_eim_cfg_data_t` | #### 返回值说明 - `ESIM_OK`：查询成功 - `其他`：查询失败 详见 `esim_result_errno_e`。 ### 添加eIM信息 #### esim_intf_initail_eim_add #### 函数原型 ```c esim_result_errno_e esim_intf_initail_eim_add( qosa_bool_t state, qosa_uint8_t seq, qosa_uint8_t *data, qosa_uint32_t data_len); ``` #### 功能描述 此功能用于往eUICC中添加首个eIM信息，eIM数据较长时，支持数据分包传输。 若eUICC中已有eIM信息，此接口会报错，SGP.32强制要求。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | state | qosa_bool_t | 是 | 无 | 数据包状态
`QOSA_TRUE` 表示非最后一包数据
`QOSA_FALSE` 表示最后一包数据 | | seq | qosa_uint8_t | 是 | 大于0 | 分包序列号
seq必须从0开始，标识起始数据包。
后续每个数据包的seq必须按序递增1，不允许出现乱序 | | data | qosa_uint8_t * | 是 | 无 | 分包数据，二进制转换成十六进制字符串的数据 | | data_len | qosa_uint32_t | 是 | 无 | 分包数据长度，必须是偶数 | #### 返回值说明 - `ESIM_OK`：添加成功 - `其他`：添加失败 详见 `esim_result_errno_e`。 ### 立即启用备用Profile #### esim_intf_fallback_exte #### 函数原型 ```c esim_result_errno_e esim_intf_fallback_exte(void); ``` #### 功能描述 此功能用于立即触发fallback，切至已设好的备用Profile；前提：Profile支持fallback并已在eIM标记为备用。 #### 参数说明 无 #### 返回值说明 - `ESIM_OK`：启用成功 - `其他`：启用失败 详见 `esim_result_errno_e`。 ### 备用Profile回退 #### esim_intf_fallback_return_exte #### 函数原型 ```c esim_result_errno_e esim_intf_fallback_return_exte(void); ``` #### 功能描述 此功能用于即刻退出fallback，恢复至原始Profile。仅当当前启用的Profile是通过 `esim_intf_fallback_exte()` 实现启用时才适用。 #### 参数说明 无 #### 返回值说明 - `ESIM_OK`：回退成功 - `其他`：回退失败 详见 `esim_result_errno_e`。 ```{note} **注意：** 1. `esim_intf_fallback_return_exte()` 和 `esim_intf_fallback_exte()` 应配套使用。 ``` ### eUICC内存重置 #### esim_intf_euicc_memory_reset #### 函数原型 ```c esim_result_errno_e esim_intf_euicc_memory_reset(euicc_reset_option_e opt); ``` #### 功能描述 此功能用于重置eUICC的内存，重置不可恢复，慎用。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | opt | `euicc_reset_option_e` | 是 | 无 | 重置内存块选项
当前只支持设置 `RESET_EIM_CONFIGDATA`，用于重置eIM信息 | #### 返回值说明 - `ESIM_OK`：重置成功 - `其他`：重置失败 详见 `esim_result_errno_e`。 ### 设置轮询延迟时间 #### esim_intf_ipa_pll_delay_set #### 函数原型 ```c esim_result_errno_e esim_intf_ipa_pll_delay_set(int delay_s); ``` #### 功能描述 此功能用于设置eSIM初始化完成后IPA初次轮询操作延迟启动。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | delay_s | int | 是 | [0, 60~900] | 单位 秒
0关闭延迟功能 | #### 返回值说明 - `ESIM_OK`：设置成功 - `其他`：设置失败 详见 `esim_result_errno_e`。 ### 查询轮询延迟时间 #### esim_intf_ipa_pll_delay_get #### 函数原型 ```c esim_result_errno_e esim_intf_ipa_pll_delay_get(int *delay_s); ``` #### 功能描述 此功能用于查询eSIM初始化完成后IPA初次轮询操作延迟启动。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | delay_s | int * | 是 | [0, 60~900] | 用于存储轮询延迟时间 | #### 返回值说明 - `ESIM_OK`：查询成功 - `其他`：查询失败 详见 `esim_result_errno_e`。 ### 遍历通知 #### esim_intf_notification_list #### 函数原型 ```c esim_result_errno_e esim_intf_notification_list(esim_notification_event_e notification_event, qosa_q_type_t *ntf_list); ``` #### 功能描述 此功能用于遍历eUICC中缓存的事件通知，只遍历通知的基本信息。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | notification_event | `esim_notification_event_e` | 是 | 无 | 需要遍历的通知类型
详见 `esim_notification_event_e` | | ntf_list | `qosa_q_type_t` * | 是 | 无 | 存储通知基本信息的链表，使用前须完成初始化
节点类型 `esim_ntf_info_t` | #### 返回值说明 - `ESIM_OK`：遍历成功 - `其他`：遍历失败 详见 `esim_result_errno_e`。 ```{note} **注意：** 1. SGP.32未定义此功能，此功能定义在SGP.22中。 ``` ### 删除通知 #### esim_intf_notification_remove #### 函数原型 ```c esim_result_errno_e esim_intf_notification_remove(int seq_num); ``` #### 功能描述 此功能用于根据序列号从eUICC缓存的事件通知列表中删除一个事件通知。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | seq_num | int | 是 | 无 | 通知序列号 | #### 返回值说明 - `ESIM_OK`：删除成功 - `其他`：删除失败 详见 `esim_result_errno_e`。 ### 获取通知 #### esim_intf_retrieve_notification_by_seq #### 函数原型 ```c esim_result_errno_e esim_intf_retrieve_notification_by_seq(int seq_num, esim_ntf_complete_info_t *ntf_info); ``` #### 功能描述 此功能用于根据提供的序列号，从eUICC缓存的事件通知列表中，查询并返回相应通知的完整内容。 通知数据以Base64格式编码，对应通知的原始数据。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | seq_num | int | 是 | 无 | 通知序列号 | | ntf_info | `esim_ntf_complete_info_t` * | 是 | 无 | 用于存储通知内容 | #### 返回值说明 - `ESIM_OK`：获取成功 - `其他`：获取失败 详见 `esim_result_errno_e`。 ### 上报通知 #### esim_intf_report_notification_by_seq #### 函数原型 ```c esim_result_errno_e esim_intf_report_notification_by_seq(int seq_num); ``` #### 功能描述 此功能用于根据提供的序列号，从eUICC缓存的事件通知列表中，查询并上报通知给相应的SM-DP+。 通知上报成功后会自动从eUICC缓存的事件通知列表中删除通知。 此操作需确保模组网络正常，无占用。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | seq_num | int | 是 | 无 | 通知序列号 | #### 返回值说明 - `ESIM_OK`：上报成功 - `其他`：上报失败 详见 `esim_result_errno_e`。 ### 管理Profile #### esim_intf_profile_handle #### 函数原型 ```c esim_result_errno_e esim_intf_profile_handle(esim_profile_opt_e opt, char *iccid, int iccid_len, qosa_bool_t refresh); ``` #### 功能描述 此功能用于根据提供的ICCID管理eUICC已安装的Profile状态，包括启用、停用、删除。 删除Profile会自动尝试上报删除通知到DP+，会耗时较久，超时时间60秒。 删除时需确保模组网络正常，无占用。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | opt | `esim_profile_opt_e` | 是 | 无 | 操作类型
详见 `esim_profile_opt_e` | | iccid | char * | 是 | 无 | ICCID字符串 | | iccid_len | int | 是 | 20 | ICCID长度 | | refresh | `qosa_bool_t` | 是 | 无 | 是否设置refresh标志位 | #### 返回值说明 - `ESIM_OK`：操作成功 - `其他`：操作失败 详见 `esim_result_errno_e`。 ```{note} **注意：** 1. SGP.32未定义此功能，此功能定义在SGP.22中。 ``` ### 设置昵称 #### esim_intf_profile_nickname_set #### 函数原型 ```c esim_result_errno_e esim_intf_profile_nickname_set(char *nickname, int nickname_len, char *iccid, int iccid_len); ``` #### 功能描述 此功能用于根据提供的ICCID给eUICC已安装的Profile状态设置昵称。 #### 参数说明 | **参数名** | **类型** | **是否必填** | **范围/单位** | **说明** | | --- | --- | --- | --- | --- | | nickname | char * | 是 | 无 | 昵称字符串 | | nickname_len | int | 是 | 0~64 | 昵称长度 | | iccid | char * | 是 | 无 | ICCID字符串 | | iccid_len | int | 是 | 20 | ICCID长度 | #### 返回值说明 - `ESIM_OK`：设置成功 - `其他`：设置失败 详见 `esim_result_errno_e`。 ```{note} **注意：** 1. SGP.32未定义此功能，此功能定义在SGP.22中。 ``` ## 数据结构定义 ### esim_data_array_t结构体定义 ```cpp /** * @struct esim_data_array_t * @brief 用于保存通用的小数据量数据存储需要的空间信息 */ typedef struct { qosa_uint8_t data_len; /*!< 存储空间长度 */ qosa_uint8_t data[ESIM_DATA_ARRAY_MAX_LEN]; /*!< 存储空间数据 */ } esim_data_array_t; ``` ### esim_data_ptr_t结构体定义 ```cpp /** * @struct esim_data_ptr_t * @brief 用于保存大数量量信息传输需要的空间信息 */ typedef struct { qosa_uint32_t data_len; /*!< 存储空间长度 */ char *data; /*!< 数据传输指针，如果由AT向SDK传入，由SDK释放，反之由AT释放*/ } esim_data_ptr_t; ``` ### esim_profile_info_t结构体定义 ```cpp /** * @struct esim_profile_info_t * @brief 用于保存单个Profile中的信息内容 */ typedef struct { qosa_q_link_type_t link; /*!< 链表节点 */ esim_data_array_t iccid_info; /*!< ICCID */ qosa_int8_t status; /*!< Profile状态 */ qosa_int8_t pro_class; /*!< Profile class */ esim_data_array_t nickname_info; /*!< Nickname数据 */ esim_data_array_t provider; /*!< Provider数据 */ esim_data_array_t name_info; /*!< Profile name数据 */ } esim_profile_info_t; ``` ### esim_ntf_info_t结构体定义 ```cpp /** * @struct esim_ntf_info_t * @brief 用于保存notification元数据相关信息 */ typedef struct { qosa_q_link_type_t link; /*!< 链表节点 */ qosa_int32_t type; /*!< notification类型 */ qosa_int32_t seq_num; /*!< notification编号 */ esim_data_array_t iccid_info; /*!< iccid */ } esim_ntf_info_t; ``` ### esim_ntf_complete_info_t结构体定义 ```cpp /** * @struct esim_ntf_complete_info_t * @brief 用于保存notification 完整信息 */ typedef struct { qosa_q_link_type_t link; /*!< 链表节点 */ qosa_int32_t type; /*!< notification类型 */ qosa_int32_t seq_num; /*!< notification编号*/ esim_data_array_t iccid_info; /*!< ICCID */ esim_data_array_t smdpp_add; /*!< SM-DP+ 地址 */ esim_data_ptr_t ntf_data; /*!< notification BASE64编码后的完整数据 */ } esim_ntf_complete_info_t; ``` ### esim_smdpp_indirect_result_t结构体定义 ```cpp /** * @struct esim_smdpp_indirect_result_t * @brief 用于间接下载时，存储请求SM-DP+的数据 */ typedef struct { esim_result_errno_e ret; // 返回结果,成功为ESIM_OK,失败为其他错误码 esim_data_array_t smdpp_add; // DP+地址 esim_data_array_t url; // DP+ Path esim_data_ptr_t req_body; // 请求json数据 qosa_bool_t end_flag; // 当下载出现错误或下载完成时为TRUE } esim_smdpp_indirect_result_t; ``` ### esim_eim_cfg_data_t结构体定义 ```cpp /** * @struct esim_eim_cfg_data_t * @brief 用于存储eIM信息 */ typedef struct { qosa_q_link_type_t link; /*!< 链表节点 */ esim_data_array_t eim_id; /*!< eIM服务器标识符 */ esim_data_array_t eim_fqdn; /*!< eIM服务器或中间服务器的FQDN域名 */ qosa_int8_t eim_id_type; /*!< eIM标识类型 */ qosa_int32_t association_token; /*!< 关联令牌，用于会话绑定 */ esim_data_ptr_t eim_public_key_data; /*!< eIM公钥/证书数据，用于eUICC验证数据包签名 */ esim_data_ptr_t trusted_public_key_data_tls; /*!< TLS信任公钥/证书链，用于eIM服务器身份认证 */ qosa_int32_t eim_supported_protocol; /*!< eIM支持的协议版本 */ esim_data_array_t euicc_ci_pk_id; /*!< eUICC上用于签名的CI公钥标识符 */ qosa_bool_t indirect_profile_download; /*!< 是否支持通过指定协议的间接Profile下载 */ } esim_eim_cfg_data_t; ``` ### esim_ipa_timer_cfg_t结构体定义 ```cpp /** * @struct esim_ipa_timer_cfg_t * @brief 用于存储IPA轮询和rollback的时间配置 */ typedef struct esim_ipa_timer_cfg { qosa_uint32_t ipa_poll_interval; /*!< IPA轮询间隔参数（单位：秒） */ qosa_uint32_t rollback_limit; /*!< rollback参数（单位：秒） */ }esim_ipa_timer_cfg_t; ``` ## 枚举类型定义 ### euicc_reset_option_e枚举定义 ```c /** * @enum euicc_reset_option_e * @brief 用于选择eUICC内存重置选项 */ typedef enum { DELETE_OPERATIONAL_PROFILES = 0, DELETE_FIELD_LOADED_TEST_PROFILES, RESET_DEFAULT_SMDP_ADDRESS, DELETE_PRELOADED_TEST_PROFILES, DELETE_PROVISIONING_PROFILES, RESET_EIM_CONFIGDATA, RESET_IMMEDIATE_ENABLE_CONFIG, }euicc_reset_option_e; ``` ### esim_notification_event_e枚举定义 ```c /** * @enum esim_notification_event_e * @brief 用于选择eSIM通知类型 */ typedef enum { LPA_NOTIFICATION_EVENT_INSTALL = 0x0780, /*!< profile install events */ LPA_NOTIFICATION_EVENT_ENABLE = 0x0640, /*!< profile enable events */ LPA_NOTIFICATION_EVENT_DISABLE = 0x0520, /*!< profile disable events */ LPA_NOTIFICATION_EVENT_DELETE = 0x0410, /*!< profile delete events */ LPA_NOTIFICATION_EVENT_ALL = 0x04F0 /*!< all profile events */ }esim_notification_event_e; ``` ### esim_profile_opt_e枚举定义 ```c /** * @enum esim_profile_opt_e * @brief 用于AT命令操作Profile操作选项 */ typedef enum { ESIM_PROFILE_OPT_ENABLE = 0, ESIM_PROFILE_OPT_DISABLE, ESIM_PROFILE_OPT_DELETE, } esim_profile_opt_e; ``` ## 宏定义 ```cpp #define ESIM_IMEI_MAX_LEN 16 /** 用于保存小数据量数组空间信息长度 */ #define ESIM_DATA_ARRAY_MAX_LEN 128 /** nickname理论上的最大长度 */ #define ESIM_NICKNAME_MAX_LEN 64 #define ESIM_ICCID_STR_LEN 20 // eSIM ICCID字符串长度定义 #define ESIM_ICCID_BYTE_LEN 10 // eSIM ICCID byte长度定义 #define ESIM_EID_STR_LEN 32 // eSIM EID字符串长度定义 #define ESIM_NOTIFICATION_DATA_MAX_LEN 4096 // eSIM通知数据最大长度定义 #define ESIM_SMDPP_ADDRESS_MAX_LEN 128 // eSIM SMDPP地址最大长度定义 #define ESIM_AC_CC_CODE_MAX_LEN 128 // 激活码和确认码最大长度定义 #define ESIM_EIM_ID_MAX_LEN 128 // EIM ID最大长度定义 #define ESIM_APN_MAX_LEN 128 // APN string max length #define ESIM_EIM_POLL_INTERVAL_SEC_MIN 120 // 轮训最小间隔时间定义（单位：秒） #define ESIM_EIM_POLL_INTERVAL_SEC_MAX 3888000 // 轮训最大间隔时间定义（单位：秒, 45天） #define ESIM_EIM_POLL_DELAY_SEC_MIN 60 // 轮训最小延迟时间定义（单位：秒） #define ESIM_EIM_POLL_DELAY_SEC_MAX 900 // 轮训最大延迟时间定义（单位：秒） ``` # 应用示例 ### eSIM初始化 ```c int ret = 0; ret = esim_intf_server_start(); utils_printf("create at process task:%x", ret); ``` ### 获取EID ```c char eid[ESIM_EID_STR_LEN+1] = {0}; esim_result_errno_e ret = ESIM_INVALID_PARAM_ERR; qosa_memset(eid, 0x00, ESIM_EID_STR_LEN+1); ret = esim_intf_eid_get(eid); utils_printf("eid:%s", eid); ``` ### 获取所有Profile ```c esim_result_errno_e ret = ESIM_INVALID_PARAM_ERR; int num = 0; qosa_q_type_t profile_list; esim_profile_info_t *profile_ptr = NULL; qosa_q_init(&profile_list); ret = esim_intf_get_all_profile(&profile_list); if(ret == ESIM_OK) { num = profile_list.cnt; utils_printf("profile cnt:%d", num); for(i = 0; i < num; i++) { profile_ptr = qosa_q_get(&profile_list); utils_printf("profile_ptr:%x", profile_ptr); if(profile_ptr != NULL) { utils_printf("\"%s\",%d,\"%s\",%d,\"%s\",\"%s\"", profile_ptr->iccid_info.data, profile_ptr->status, profile_ptr->nickname_info.data, profile_ptr->pro_class, profile_ptr->name_info.data, profile_ptr->provider.data); qosa_free(profile_ptr); profile_ptr = NULL; } } } qosa_q_destroy(&profile_list); ``` ### 获取eSIM SDK版本号 ```c char ver[64] = {0}; int len = 0; qosa_memset(ver, 0x00, 64); len = esim_intf_ver_get(ver, 64); utils_printf("esim ver:%s", ver); ``` ### 内部网络下载Profile ```cpp qosa_task_t g_lpa_rsp_task = QOSA_NULL; typedef struct { char ac_code[ESIM_AC_CC_CODE_MAX_LEN]; char cc_code[ESIM_AC_CC_CODE_MAX_LEN]; }lpa_rsp_arg_t; static void esim_lpa_rsp_start_main(void *arg) { esim_result_errno_e ret = ESIM_OK; qosa_task_t tsak_tmp = NULL; esim_data_array_t iccid_str = {0}; lpa_rsp_arg_t *argv = (lpa_rsp_arg_t *)arg; if(argv != NULL) { ret = esim_intf_direct_download_profile(argv->ac_code, qosa_strlen(argv->ac_code), argv->cc_code, qosa_strlen(argv->cc_code), &iccid_str); if(ret == ESIM_OK) { utils_printf("download success, iccid:%s", iccid_str->data); } else { utils_printf("download fail ,ret: %X", ret); } qosa_free(argv); } tsak_tmp = g_lpa_rsp_task; g_lpa_rsp_task = NULL; qosa_task_delete(tsak_tmp); } static esim_result_errno_e esim_lpa_profile_download(lpa_rsp_arg_t *argv) { esim_result_errno_e ret = ESIM_OK; int qosa_err = 0; qosa_err = qosa_task_create((qosa_task_t*)&g_lpa_rsp_task, 10240, QOSA_PRIORITY_ABOVE_NORMAL, "ESIM_RSP_THREAD", &esim_lpa_rsp_start_main, (void *)argv); if(qosa_err != 0) { qosa_free(argv); ret = ESIM_ERROR_GENERAL; utils_printf("create rsp task error "); } return ret; } ``` ### 启用Profile ```c esim_result_errno_e ret = ESIM_INVALID_PARAM_ERR; char iccid[] = "89320420000111550651"; ret = esim_intf_profile_handle(ESIM_PROFILE_OPT_ENABLE, iccid, qosa_strlen(iccid), QOSA_TRUE); utils_printf("iccid[%s] enable ret:%x", iccid, ret); ``` ### 设置IPA轮询 ```c esim_result_errno_e ret = ESIM_INVALID_PARAM_ERR; qosa_uint32_t sec = 3600; ret = esim_intf_poll_interval_set(&sec); utils_printf("ipa poll ret: %x", ret); ``` ### 添加eIM ```c esim_result_errno_e ret = ESIM_OK; qosa_uint8_t eim_data [] = "A081C13081BE801D312E332E362E312E342E312E35383830392E3939392E35383830392E318123696F742D6573696D2D676C6F62616C2D676174657761792E7175656374656C2E636F6D830100A55BA059301306072A8648CE3D020106082A8648CE3D03010703420004382B53EAE204617FC0EB8593CF3F8D1A67A79BA45D1676CF18E699C8F552D2059E61399CFDEF1693B6E300C49168EED78366E0FD2D4FC566FD9029F8EE2ADAB087020780881481370F5125D0B1D408D4C3B232E6D25E795BEBFB" ret = esim_intf_initail_eim_add(QOSA_FALSE, 0, eim_data, qosa_strlen(eim_data)); utils_printf("eim add ret:%x", ret); ``` ### 分包添加eIM ```c esim_result_errno_e ret = ESIM_OK; qosa_uint8_t eim_data1 [] = "A081C13081BE801D312E332E362E312E342E312E35383830392E3939392E35383830392E318123696F742D6573696D2D676C6F62616C2D676174657761792E7175656374656C2E636F6D830100A55BA059301306072A8648CE3D02010608" qosa_uint8_t eim_data2 [] = "2A8648CE3D03010703420004382B53EAE204617FC0EB8593CF3F8D1A67A79BA45D1676CF18E699C8F552D2059E61399CFDEF1693B6E300C49168EED78366E0FD2D4FC566FD9029F8EE2ADAB087020780881481370F5125D0B1D408D4C3B232E6D25E795BEBFB" ret = esim_intf_initail_eim_add(QOSA_TRUE, 0, eim_data1, qosa_strlen(eim_data1)); if(ret == ESIM_OK) { ret = esim_intf_initail_eim_add(QOSA_FALSE, 1, eim_data2, qosa_strlen(eim_data2)); utils_printf("eim add ret:%x", ret); } ``` # 常见问题排查指南 ## 无法下载安装Profile - AccCode是否错误，可向运营商进行确认。 - 当前的设备或PC机是否可以正常访问从AccCode中解析出的url地址。 - 是否重复下载安装Profile。 - 是否运营商进行限制，同一个AccCode只能使用一次，需和运营商进行确定。 - 网络信号是否太弱，网络不稳定。 ## 下载安装Profile后无法上网 如遇到下载安装Profile成功后无法上网，请做一次CFUN=0/1的切换操作。如依然无法上网，请按如下方面进行检查。 - SIM卡状态是否异常 - 下载安装的Profile是否已正常激活。 - 下载安装的Profile是否有效，可向运营商确认。 - 是否设备未执行拨号操作（如设置设备不自动激活，请检查是否未执行激活操作）。