# 一键SMS

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# 功能概述

一键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*（短信存储空间满事件）。

- **函数原型**

```c
void qosa_easy_sms_init_config(void);
```

- **参数说明**  
  无

- **返回值说明**  
  无

### qosa_easy_sms_register_event_cb

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

- **函数原型**

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

- **返回值说明**

*QOSA_EASY_SMS_SUCCESS*：函数执行成功

其他值：函数执行失败；详见 [*qosa_easy_sms_errcode_e*](#qosaeasysmserrcodee)

#### qosa_easy_sms_event_cb_t

- **函数原型**

```cpp
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*](#qosaeasysmsevente) |
| *ctx* | 输入 | void | 用户自定义上下文指针 |

- **返回值说明**  
  无

### qosa_easy_sms_receive_text_cb_register

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

- **函数原型**

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

- **返回值说明**  
  *QOSA_EASY_SMS_SUCCESS*：函数执行成功  
  其他值：函数执行失败；详见 [*qosa_easy_sms_errcode_e*](#qosaeasysmserrcodee)

### qosa_easy_sms_receive_pdu_cb_register

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

- **函数原型**

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

- **返回值说明**  
  *QOSA_EASY_SMS_SUCCESS*：函数执行成功  
  其他值：函数执行失败；详见 [*qosa_easy_sms_errcode_e*](#qosaeasysmserrcodee)

### qosa_easy_sms_set_param

- **功能描述**  
  配置一键SMS的参数。

- **函数原型**

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

- **返回值说明**  
  *QOSA_EASY_SMS_SUCCESS*：函数执行成功  
  其他值：函数执行失败；详见 [*qosa_easy_sms_errcode_e*](#qosaeasysmserrcodee)

### qosa_easy_sms_get_param

- **功能描述**  
  获取一键SMS的配置参数。

- **函数原型**

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

- **返回值说明**  
  *QOSA_EASY_SMS_SUCCESS*：函数执行成功  
  其他值：函数执行失败；详见 [*qosa_easy_sms_errcode_e*](#qosaeasysmserrcodee)

### qosa_easy_sms_send_text_msg

- **功能描述**  
  同步模式下发送文本格式短信。

- **函数原型**

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

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

### qosa_easy_sms_send_pdu_msg

- **功能描述**  
  同步模式下发送PDU格式短信。

- **函数原型**

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

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

### qosa_easy_sms_delete_msg

- **功能描述**  
  同步模式下清空短信存储区内全部短信。

- **函数原型**

```c
qosa_easy_sms_errcode_e qosa_easy_sms_delete_msg(void);
```

- **参数说明**  
  无

- **返回值说明**  
  *QOSA_EASY_SMS_SUCCESS*：函数执行成功  
  其他值：函数执行失败；详见 [*qosa_easy_sms_errcode_e*](#qosaeasysmserrcodee)

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

## 结构体定义

### qosa_easy_sms_param_t

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

```c
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*](#qosaeasysmsformate)；默认值：QOSA_EASY_SMS_TEXT（文本格式） |
| *coding* | *qosa_easy_sms_coding_e* | 短信编码格式；详见 [*qosa_easy_sms_coding_e*](#qosaeasysmscodinge)；默认值：*QOSA_EASY_SMS_CODING_UCS2*（UCS2） |
| *storage* | *qosa_easy_sms_storage_t* | 短信存储偏好；详见 [*qosa_easy_sms_storage_t*](#qosaeasysmsstoraget)；<br>默认值：<br>*mem1* = *QOSA_SMS_STOR_ME*<br>*mem2* = *QOSA_SMS_STOR_ME*<br>*mem3* = *QOSA_SMS_STOR_ME* |
| *smsc* | char * | 短信中心地址；默认值：NULL |
| *delivery_report* | qosa_bool_t | 是否打开短信回执；默认值：QOSA_TRUE<br>*QOSA_TRUE*：打开<br>*QOSA_FALSE*：关闭 |
| *vp* | qosa_uint8_t | 短信有效期；取值范围：0~0xFF；默认值：0xFF；具体计算方式请参考<br>*3GPP TS 23.040 9.2.3.12.1 TP-VP (Relative format)* |
| *dcs* | qosa_uint8_t | 编码方案，由DCS的比特位2和3决定<br>*00*：7-bit <br>*01*：8-bit<br>*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<br>*QOSA_TRUE*：忽略<br>*QOSA_FALSE*：不忽略 |
| reserved | qosa_uint8_t | 预留 |

### qosa_easy_sms_storage_t

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

```cpp
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*](../../../%E7%BD%91%E7%BB%9C%E4%B8%8E%E9%80%9A%E4%BF%A1/SMS/SMS.md#qosasmsstor_e) |
| *mem2* | *qosa_sms_stor_e* | 存储器2：用于写入和发送短信；详见 [*qosa_sms_stor_e*](../../../%E7%BD%91%E7%BB%9C%E4%B8%8E%E9%80%9A%E4%BF%A1/SMS/SMS.md#qosasmsstor_e) |
| *mem3* | *qosa_sms_stor_e* | 存储器3：用于存储接收到的短信；详见 [*qosa_sms_stor_e*](../../../%E7%BD%91%E7%BB%9C%E4%B8%8E%E9%80%9A%E4%BF%A1/SMS/SMS.md#qosasmsstor_e) |

## 枚举定义

### qosa_easy_sms_errcode_e

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

```c
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枚举定义如下：

```c
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

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

```c
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

短信格式枚举定义如下：

```c
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* | 文本格式 |

# 应用逻辑流程图

```{image} images/board_Ay1LwEmHrhZ7MBbOHzjc5aMAn6g.jpg
:width: 820px
:height: 1030px
:align: center
```

# 示例代码

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

# 开发约束与使用规范

1. 一键SMS的API不能与AT命令并发执行。

2. 调用一键SMS API时，禁止并行调用SMS API。