一键SMS¶

功能概述¶

一键SMS功能内部集成短信收发、事件监听、参数配置、存储管理等多个接口，大幅简化短信业务开发流程：发送短信仅需填写接收号码与内容，内部自动完成编码处理；接收短信支持注册对应回调，收到消息后自动完成数据解析；同时提供短信批量删除、全局参数配置等管理能力。

一键SMS API¶

头文件¶

easy_sms.h

函数概览¶

函数	说明
qosa_easy_sms_init_config()	初始化一键SMS功能
qosa_easy_sms_register_event_cb()	注册短信事件回调函数
qosa_easy_sms_receive_text_cb_register()	注册文本格式短信专属接收回调函数
qosa_easy_sms_receive_pdu_cb_register()	注册PDU格式短信专属接收回调函数
qosa_easy_sms_set_param()	配置一键SMS的参数
qosa_easy_sms_get_param()	获取一键SMS的配置参数
qosa_easy_sms_send_text_msg()	同步模式下发送文本格式短信
qosa_easy_sms_send_pdu_msg()	同步模式下发送PDU格式短信
qosa_easy_sms_delete_msg()	同步模式下清空短信存储区内全部短信

函数详解¶

qosa_easy_sms_init_config¶

功能描述
初始化一键SMS功能，自动注册 QOSA_EVENT_MODEM_SMS_STATUS（短信初始化状态事件）、QOSA_EVENT_MODEM_SMS_NEW_MSG（新短信事件）和 QOSA_EVENT_MODEM_SMS_STORAGE_FULL（短信存储空间满事件）。
函数原型

void qosa_easy_sms_init_config(void);

参数说明
无
返回值说明
无

qosa_easy_sms_register_event_cb¶

功能描述
注册短信事件回调函数。当发生短信初始化完成、新消息到达、存储空间满等事件时触发此回调函数，上报事件信息。
函数原型

qosa_easy_sms_errcode_e qosa_easy_sms_register_event_cb(qosa_easy_sms_event_cb_t cb);

参数说明

参数	输入/输出	类型	说明
cb	输入	qosa_easy_sms_event_cb_t	短信事件回调函数指针；详见 qosa_easy_sms_event_cb_t

返回值说明

QOSA_EASY_SMS_SUCCESS：函数执行成功

其他值：函数执行失败；详见 qosa_easy_sms_errcode_e

qosa_easy_sms_event_cb_t¶

函数原型

typedef void (*qosa_easy_sms_event_cb_t)(qosa_uint8_t sim, qosa_uint8_t event_id, void *ctx);

参数说明

参数	输入/输出	类型	说明
sim	输入	qosa_uint8_t	SIM ID
event_id	输入	qosa_uint8_t	短信事件类型 ID；详见 qosa_easy_sms_event_e
ctx	输入	void	用户自定义上下文指针

返回值说明
无

qosa_easy_sms_receive_text_cb_register¶

功能描述
注册文本格式短信专属接收回调函数。
函数原型

qosa_easy_sms_errcode_e qosa_easy_sms_receive_text_cb_register(qosa_easy_sms_event_cb_t cb);

参数说明

参数	输入/输出	类型	说明
cb	输入	qosa_easy_sms_event_cb_t	短信事件回调函数指针；详见 qosa_easy_sms_event_cb_t

返回值说明
QOSA_EASY_SMS_SUCCESS：函数执行成功
其他值：函数执行失败；详见 qosa_easy_sms_errcode_e

qosa_easy_sms_receive_pdu_cb_register¶

功能描述
注册PDU格式短信专属接收回调函数。
函数原型

qosa_easy_sms_errcode_e qosa_easy_sms_receive_pdu_cb_register(qosa_easy_sms_event_cb_t cb)；

参数说明

参数	输入/输出	类型	说明
cb	输入	qosa_easy_sms_event_cb_t	短信事件回调函数指针；详见 qosa_easy_sms_event_cb_t

返回值说明
QOSA_EASY_SMS_SUCCESS：函数执行成功
其他值：函数执行失败；详见 qosa_easy_sms_errcode_e

qosa_easy_sms_set_param¶

功能描述
配置一键SMS的参数。
函数原型

qosa_easy_sms_errcode_e qosa_easy_sms_set_param(const qosa_easy_sms_param_t *tab);

参数说明

参数	输入/输出	类型	说明
tab	输入	const qosa_easy_sms_param_t *	一键SMS的配置参数；详见 qosa_easy_sms_param_t

返回值说明
QOSA_EASY_SMS_SUCCESS：函数执行成功
其他值：函数执行失败；详见 qosa_easy_sms_errcode_e

qosa_easy_sms_get_param¶

功能描述
获取一键SMS的配置参数。
函数原型

qosa_easy_sms_errcode_e qosa_easy_sms_get_param(qosa_easy_sms_param_t *tab);

参数说明

参数	输入/输出	类型	说明
tab	输出	qosa_easy_sms_param_t *	一键SMS的配置参数；详见 qosa_easy_sms_param_t

返回值说明
QOSA_EASY_SMS_SUCCESS：函数执行成功
其他值：函数执行失败；详见 qosa_easy_sms_errcode_e

qosa_easy_sms_send_text_msg¶

功能描述
同步模式下发送文本格式短信。
函数原型

qosa_easy_sms_errcode_e qosa_easy_sms_send_text_msg(const char *phone_number, const char *message_text);

参数说明

参数	输入/输出	类型	说明
phone_number	输入	const char *	接收方手机号
message_text	输入	const char *	UCS2编码后的短信内容

返回值说明
QOSA_EASY_SMS_SUCCESS：函数执行成功
其他值：函数执行失败；详见 qosa_easy_sms_errcode_e

备注

文本短信强制使用UCS2编码，message_text 必须为已完成UCS2编码的字符串；例如： “4F60597D”代表“你好”。

qosa_easy_sms_send_pdu_msg¶

功能描述
同步模式下发送PDU格式短信。
函数原型

qosa_easy_sms_errcode_e qosa_easy_sms_send_pdu_msg(const char *message_pdu, qosa_uint16_t pdu_length);

参数说明

参数	输入/输出	类型	说明
message_pdu	输入	const char *	完整的PDU格式短信数据
pdu_length	输入	qosa_uint16_t	PDU格式短信中有效的数据长度

返回值说明
QOSA_EASY_SMS_SUCCESS：函数执行成功
其他值：函数执行失败；详见 qosa_easy_sms_errcode_e

备注

pdu_length 为有效TP数据字节长度，短信中心前缀字节不计入该长度；例如： “00 110005910180F60004FF0431323334” //去除“00”，剩下一共15字节 “04910180F6 110005910180F60004FF0431323334” //去除“04910180F6”，剩下一共15字节

qosa_easy_sms_delete_msg¶

功能描述
同步模式下清空短信存储区内全部短信。
函数原型

qosa_easy_sms_errcode_e qosa_easy_sms_delete_msg(void);

参数说明
无
返回值说明
QOSA_EASY_SMS_SUCCESS：函数执行成功
其他值：函数执行失败；详见 qosa_easy_sms_errcode_e

备注

此函数会删除短信存储区内全部短信，不支持指定单条短信。

结构体定义¶

qosa_easy_sms_param_t¶

一键SMS的配置参数结构体定义如下：

typedef struct
{
    qosa_uint8_t            simid;           
    qosa_easy_sms_format_e  format;         
    qosa_easy_sms_coding_e  coding;       
    qosa_easy_sms_storage_t storage;        
    char                   *smsc;         
    qosa_bool_t             delivery_report;
    qosa_uint8_t            vp;              
    qosa_uint8_t            dcs;            
    qosa_uint8_t            smc_retry_cnt;  
    qosa_uint8_t            smr_retry_cnt;  
    qosa_bool_t             ignore_cscs;   
    qosa_uint8_t            reserved[4];  
} qosa_easy_sms_param_t;

参数	类型	说明
simid	qosa_uint8_t	SIM ID；默认值：0
format	qosa_easy_sms_format_e	短信格式；详见 qosa_easy_sms_format_e；默认值：QOSA_EASY_SMS_TEXT（文本格式）
coding	qosa_easy_sms_coding_e	短信编码格式；详见 qosa_easy_sms_coding_e；默认值：QOSA_EASY_SMS_CODING_UCS2（UCS2）
storage	qosa_easy_sms_storage_t	短信存储偏好；详见 qosa_easy_sms_storage_t；默认值： mem1 = QOSA_SMS_STOR_ME mem2 = QOSA_SMS_STOR_ME mem3 = QOSA_SMS_STOR_ME
smsc	char *	短信中心地址；默认值：NULL
delivery_report	qosa_bool_t	是否打开短信回执；默认值：QOSA_TRUE QOSA_TRUE：打开 QOSA_FALSE：关闭
vp	qosa_uint8_t	短信有效期；取值范围：0~0xFF；默认值：0xFF；具体计算方式请参考 3GPP TS 23.040 9.2.3.12.1 TP-VP (Relative format)
dcs	qosa_uint8_t	编码方案，由DCS的比特位2和3决定 00：7-bit 01：8-bit 10：UCS2
smc_retry_cnt	qosa_uint8_t	SMC层重试次数；默认值：0
smr_retry_cnt	qosa_uint8_t	SMR层重试次数；默认值：0
ignore_cscs	qosa_bool_t	是否忽略CSCS配置；默认值：QOSA_FALSE QOSA_TRUE：忽略 QOSA_FALSE：不忽略
reserved	qosa_uint8_t	预留

qosa_easy_sms_storage_t¶

短信存储偏好结构体定义如下：

typedef struct
{
    qosa_sms_stor_e mem1;   
    qosa_sms_stor_e mem2;  
    qosa_sms_stor_e mem3;  
} qosa_easy_sms_storage_t;

参数	类型	说明
mem1	qosa_sms_stor_e	存储器1：用于读取和删除短信；详见 qosa_sms_stor_e
mem2	qosa_sms_stor_e	存储器2：用于写入和发送短信；详见 qosa_sms_stor_e
mem3	qosa_sms_stor_e	存储器3：用于存储接收到的短信；详见 qosa_sms_stor_e

枚举定义¶

qosa_easy_sms_errcode_e¶

一键SMS功能结果码枚举定义如下：

typedef enum
{
    QOSA_EASY_SMS_SUCCESS = 0,       
    QOSA_EASY_SMS_EXECUTE_ERROR,    
    QOSA_EASY_SMS_PARA_ERR,         
    QOSA_EASY_SMS_SEM_TIMEOUT_ERR,    
    QOSA_EASY_SMS_NO_MSG_ERR,        
    QOSA_EASY_SMS_ATTACH_FAIL,      
} qosa_easy_sms_errcode_e;

成员	说明
QOSA_EASY_SMS_SUCCESS	函数执行成功
QOSA_EASY_SMS_EXECUTE_ERROR	函数执行失败
QOSA_EASY_SMS_PARA_ERR	参数错误
QOSA_EASY_SMS_SEM_TIMEOUT_ERR	获取信号量超时
QOSA_EASY_SMS_NO_MSG_ERR	存储区无短信
QOSA_EASY_SMS_ATTACH_FAIL	注册失败

qosa_easy_sms_event_e¶

短信事件类型ID枚举定义如下：

typedef enum
{
    QOSA_EASY_SMS_INIT_OK = 0,
    QOSA_EASY_SMS_NEW_MSG,    
    QOSA_EASY_SMS_MEM_FULL,  
    QOSA_EASY_SMS_REPORT,   
    QOSA_EASY_SMS_MAX       
} qosa_easy_sms_event_e;

成员	说明
QOSA_EASY_SMS_INIT_OK	短信初始化完成
QOSA_EASY_SMS_NEW_MSG	新消息到达
QOSA_EASY_SMS_MEM_FULL	短信存储空间满
QOSA_EASY_SMS_REPORT	短信回执上报
QOSA_EASY_SMS_MAX	保留

qosa_easy_sms_coding_e¶

短信编码格式枚举定义如下：

typedef enum
{
    QOSA_EASY_SMS_CODING_GSM7 = 0,  
    QOSA_EASY_SMS_CODING_UCS2,      
} qosa_easy_sms_coding_e;

成员	说明
QOSA_EASY_SMS_CODING_GSM7	GSM7
QOSA_EASY_SMS_CODING_UCS2	UCS2

qosa_easy_sms_format_e¶

短信格式枚举定义如下：

typedef enum
{
    QOSA_EASY_SMS_PDU = 0,       
    QOSA_EASY_SMS_TEXT = 1,      
} qosa_easy_sms_format_e;

成员	说明
QOSA_EASY_SMS_PDU	PDU格式
QOSA_EASY_SMS_TEXT	文本格式

应用逻辑流程图¶

../../../_images/board_Ay1LwEmHrhZ7MBbOHzjc5aMAn6g.jpg

示例代码¶

完整示例代码请查看https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/application/one_touch/sms/sms_easy_demo.c

开发约束与使用规范¶

一键SMS的API不能与AT命令并发执行。
调用一键SMS API时，禁止并行调用SMS API。

一键SMS¶

功能概述¶

一键SMS API¶

头文件¶

函数概览¶

函数详解¶

qosa_easy_sms_init_config¶

qosa_easy_sms_register_event_cb¶

qosa_easy_sms_event_cb_t¶

qosa_easy_sms_receive_text_cb_register¶

qosa_easy_sms_receive_pdu_cb_register¶

qosa_easy_sms_set_param¶

qosa_easy_sms_get_param¶

qosa_easy_sms_send_text_msg¶

qosa_easy_sms_send_pdu_msg¶

qosa_easy_sms_delete_msg¶

结构体定义¶

qosa_easy_sms_param_t¶

qosa_easy_sms_storage_t¶

枚举定义¶

qosa_easy_sms_errcode_e¶

qosa_easy_sms_event_e¶

qosa_easy_sms_coding_e¶

qosa_easy_sms_format_e¶

应用逻辑流程图¶

示例代码¶

开发约束与使用规范¶

目录

本页