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全生命周期管理。其核心功能模块如下：
Profile本地管理
管理eSIM中的Profile，包括激活、去激活与删除操作。Profile空中下载（OTA）
通过HTTPS网络协议完成Profile远程下载。通知管理
上报Profile状态变更（如激活、去激活与删除）至SM-DP+平台。eIM本地管理
管理eSIM中的eIM（eSIM Identity Manager），包括添加和重置。IPA逻辑管理
配置IPA（IoT Profile Assistant）逻辑，控制IPA和eIM的交互。Fallback功能
当使用中的Profile失去注网能力时，自动/手动回退至预设紧急Profile，保障基础通信能力不中断。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¶
函数原型¶
int esim_intf_server_start(void);
功能描述¶
此功能用于初始化eSIM服务，主要包含创建eSIM线程，配置eSIM功能初始参数等。
参数说明¶
无
返回值说明¶
0：初始化成功other：失败
停用并释放eSIM服务¶
esim_intf_server_stop¶
函数原型¶
int esim_intf_server_stop(void);
功能描述¶
此功能用于停止eSIM服务，删除eSIM线程，并释放相应资源。
参数说明¶
无
返回值说明¶
0：初始化成功other：失败
获取operational类型的Profile¶
esim_intf_get_operational_profile¶
函数原型¶
esim_result_errno_e esim_intf_get_operational_profile(qosa_q_type_t *profile_list);
功能描述¶
此功能用于获取eUICC中operational类型的Profile信息。
参数说明¶
参数名 |
类型 |
是否必填 |
范围/单位 |
说明 |
|---|---|---|---|---|
profile_list |
|
是 |
无 |
存储Profile的链表，使用前须完成初始化 |
返回值说明¶
ESIM_OK：获取Profile成功其他：获取失败
详见 esim_result_errno_e。
获取全部的Profile¶
esim_intf_get_all_profile¶
函数原型¶
esim_result_errno_e esim_intf_get_all_profile(qosa_q_type_t *profile_list);
功能描述¶
此功能用于获取eUICC中全部的Profile信息。
参数说明¶
参数名 |
类型 |
是否必填 |
范围/单位 |
说明 |
|---|---|---|---|---|
profile_list |
|
是 |
无 |
存储Profile的链表，使用前须完成初始化 |
返回值说明¶
ESIM_OK：获取Profile成功其他：获取失败
详见 esim_result_errno_e。
获取EID¶
esim_intf_eid_get¶
函数原型¶
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¶
函数原型¶
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¶
函数原型¶
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¶
函数原型¶
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 * |
是 |
无 |
确认码（若不需要确认码，设置 |
cfmt_len |
int |
是 |
无 |
确认码长度（若不需要确认码，设置0） |
iccid_str |
|
是 |
无 |
Profile下载成功时，用于存放Profile的ICCID数据 |
返回值说明¶
ESIM_OK：Profile下载成功其他：获取失败
详见 esim_result_errno_e。
启动外部网络下载Profile¶
esim_intf_indirect_download_profile_start¶
函数原型¶
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 * |
是 |
无 |
确认码（若不需要确认码，设置 |
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¶
函数原型¶
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 |
是 |
无 |
数据包状态， |
seq |
qosa_uint8_t |
是 |
大于0 |
分包序列号 |
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¶
函数原型¶
esim_result_errno_e esim_intf_poll_interval_set(qosa_uint32_t *sec);
功能描述¶
此功能用于控制IPA对eIM的请求时机，既可以设置定期请求的间隔，也可以随时发起一次立即请求。
参数说明¶
参数名 |
类型 |
是否必填 |
范围/单位 |
说明 |
|---|---|---|---|---|
sec |
|
是 |
无 |
sec不为 |
返回值说明¶
ESIM_OK：轮询设置成功其他：轮询设置失败
详见 esim_result_errno_e。
查询IPA轮询间隔与rollback时限¶
esim_intf_ipa_time_cfg_get¶
函数原型¶
esim_result_errno_e esim_intf_ipa_time_cfg_get(esim_ipa_timer_cfg_t *time_cfg);
功能描述¶
此功能用于查询IPA设置定期请求的间隔和rollback的自动触发时间限制
参数说明¶
参数名 |
类型 |
是否必填 |
范围/单位 |
说明 |
|---|---|---|---|---|
time_cfg |
|
是 |
无 |
用于存储IPA轮询间隔与rollback时限 |
返回值说明¶
ESIM_OK：查询成功其他：查询失败
详见 esim_result_errno_e。
查询eIM信息¶
esim_intf_eim_info_get¶
函数原型¶
esim_result_errno_e esim_intf_eim_info_get(qosa_q_type_t *eim_info_list);
功能描述¶
此功能用于获取eUICC中全部的eIM信息。
参数说明¶
参数名 |
类型 |
是否必填 |
范围/单位 |
说明 |
|---|---|---|---|---|
eim_info_list |
|
是 |
无 |
存储eIM的链表，使用前须完成初始化 |
返回值说明¶
ESIM_OK：查询成功其他：查询失败
详见 esim_result_errno_e。
添加eIM信息¶
esim_intf_initail_eim_add¶
函数原型¶
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 |
是 |
无 |
数据包状态 |
seq |
qosa_uint8_t |
是 |
大于0 |
分包序列号 |
data |
qosa_uint8_t * |
是 |
无 |
分包数据，二进制转换成十六进制字符串的数据 |
data_len |
qosa_uint32_t |
是 |
无 |
分包数据长度，必须是偶数 |
返回值说明¶
ESIM_OK：添加成功其他：添加失败
详见 esim_result_errno_e。
立即启用备用Profile¶
esim_intf_fallback_exte¶
函数原型¶
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¶
函数原型¶
esim_result_errno_e esim_intf_fallback_return_exte(void);
功能描述¶
此功能用于即刻退出fallback，恢复至原始Profile。仅当当前启用的Profile是通过 esim_intf_fallback_exte() 实现启用时才适用。
参数说明¶
无
返回值说明¶
ESIM_OK：回退成功其他：回退失败
详见 esim_result_errno_e。
备注
注意：
esim_intf_fallback_return_exte()和esim_intf_fallback_exte()应配套使用。
eUICC内存重置¶
esim_intf_euicc_memory_reset¶
函数原型¶
esim_result_errno_e esim_intf_euicc_memory_reset(euicc_reset_option_e opt);
功能描述¶
此功能用于重置eUICC的内存，重置不可恢复，慎用。
参数说明¶
参数名 |
类型 |
是否必填 |
范围/单位 |
说明 |
|---|---|---|---|---|
opt |
|
是 |
无 |
重置内存块选项 |
返回值说明¶
ESIM_OK：重置成功其他：重置失败
详见 esim_result_errno_e。
设置轮询延迟时间¶
esim_intf_ipa_pll_delay_set¶
函数原型¶
esim_result_errno_e esim_intf_ipa_pll_delay_set(int delay_s);
功能描述¶
此功能用于设置eSIM初始化完成后IPA初次轮询操作延迟启动。
参数说明¶
参数名 |
类型 |
是否必填 |
范围/单位 |
说明 |
|---|---|---|---|---|
delay_s |
int |
是 |
[0, 60~900] |
单位 秒 |
返回值说明¶
ESIM_OK：设置成功其他：设置失败
详见 esim_result_errno_e。
查询轮询延迟时间¶
esim_intf_ipa_pll_delay_get¶
函数原型¶
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¶
函数原型¶
esim_result_errno_e esim_intf_notification_list(esim_notification_event_e notification_event, qosa_q_type_t *ntf_list);
功能描述¶
此功能用于遍历eUICC中缓存的事件通知，只遍历通知的基本信息。
参数说明¶
参数名 |
类型 |
是否必填 |
范围/单位 |
说明 |
|---|---|---|---|---|
notification_event |
|
是 |
无 |
需要遍历的通知类型 |
ntf_list |
|
是 |
无 |
存储通知基本信息的链表，使用前须完成初始化 |
返回值说明¶
ESIM_OK：遍历成功其他：遍历失败
详见 esim_result_errno_e。
备注
注意：
SGP.32未定义此功能，此功能定义在SGP.22中。
删除通知¶
esim_intf_notification_remove¶
函数原型¶
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¶
函数原型¶
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_OK：获取成功其他：获取失败
详见 esim_result_errno_e。
上报通知¶
esim_intf_report_notification_by_seq¶
函数原型¶
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¶
函数原型¶
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 |
|
是 |
无 |
操作类型 |
iccid |
char * |
是 |
无 |
ICCID字符串 |
iccid_len |
int |
是 |
20 |
ICCID长度 |
refresh |
|
是 |
无 |
是否设置refresh标志位 |
返回值说明¶
ESIM_OK：操作成功其他：操作失败
详见 esim_result_errno_e。
备注
注意：
SGP.32未定义此功能，此功能定义在SGP.22中。
设置昵称¶
esim_intf_profile_nickname_set¶
函数原型¶
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。
备注
注意：
SGP.32未定义此功能，此功能定义在SGP.22中。
数据结构定义¶
esim_data_array_t结构体定义¶
/**
* @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结构体定义¶
/**
* @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结构体定义¶
/**
* @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结构体定义¶
/**
* @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结构体定义¶
/**
* @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结构体定义¶
/**
* @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结构体定义¶
/**
* @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结构体定义¶
/**
* @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枚举定义¶
/**
* @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枚举定义¶
/**
* @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枚举定义¶
/**
* @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;
宏定义¶
#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初始化¶
int ret = 0;
ret = esim_intf_server_start();
utils_printf("create at process task:%x", ret);
获取EID¶
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¶
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版本号¶
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¶
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¶
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轮询¶
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¶
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¶
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是否有效，可向运营商确认。
是否设备未执行拨号操作（如设置设备不自动激活，请检查是否未执行激活操作）。