# 消息队列

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

---

# 功能概述

消息队列支持多生产者、多消费者模型。它采用先进先出的数据结构，适用于需要在多线程间安全交换消息的场景，常用于消息异步处理。例如，接收数据的线程为避免阻塞，只是将数据写入队列；另一个线程则专门处理队列中的消息。

# 消息队列API

## 头文件

*qosa_sys.h*

## 函数概览

| **函数名** | **功能描述** |
| --- | --- |
| *qosa_msgq_create()* | 创建消息队列 |
| *qosa_msgq_delete()* | 删除消息队列 |
| *qosa_msgq_release()* | 发送消息到队列 |
| *qosa_msgq_wait()* | 从队列接收消息 |
| *qosa_msgq_get_cnt()* | 获取当前队列中的消息数量 |

## 函数详解

### qosa_msgq_create

- **功能描述**  
  创建消息队列，并指定消息大小和队列容量。

- **函数原型**

```c
int qosa_msgq_create(qosa_msgq_t *msgQRef, qosa_uint32_t size, qosa_uint32_t maxNumber)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *msgQRef* | 输入 | qosa_msgq_t * | 消息队列句柄指针 |
| *size* | 输入 | qosa_uint32_t | 存储的数据类型的长度 |
| *maxNumber* | 输入 | qosa_uint32_t | 消息队列的最大消息数 |

- **返回值说明**  
  *QOSA_ERROR_OK*：函数执行成功  
  *QOSA_ERROR_MSGQ_INVALID_ERR*：参数无效  
  *QOSA_ERROR_MSGQ_CREATE_ERR*：创建失败

### qosa_msgq_delete

- **功能描述**  
  删除消息队列，并释放所有相关资源。

- **函数原型**

```c
int qosa_msgq_delete(qosa_msgq_t msgQRef)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *msgQRef* | 输入 | qosa_msgq_t | 消息队列句柄 |

- **返回值说明**  
  *QOSA_ERROR_OK*：函数执行成功  
  *QOSA_ERROR_MSGQ_INVALID_ERR*：参数无效

```{note}
1. 调用此函数前，请确保没有任何任务正在阻塞等待或访问该队列。
2. 队列被删除时，其中未处理的消息会被丢弃。
3. 删除成功后，该句柄将立即失效。
```

### qosa_msgq_release

- **功能描述**  
  发送消息到队列。

- **函数原型**

```c
int qosa_msgq_release(qosa_msgq_t msgQRef, qosa_uint32_t size, qosa_uint8_t *value, qosa_uint32_t timeout)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *msgQRef* | 输入 | qosa_msgq_t | 消息队列句柄 |
| *size* | 输入 | qosa_uint32_t | 发送消息的大小（必须与创建队列时指定的 *size* 一致） |
| *value* | 输入 | qosa_uint8_t * | 指向消息数据的指针 |
| *timeout* | 输入 | qosa_uint32_t | 等待超时时间。单位：毫秒<br>*QOSA_WAIT_FOREVER*：永久等待<br>*QOSA_NO_WAIT*：不等待 |

- **返回值说明**  
  *QOSA_ERROR_OK*：函数执行成功  
  *QOSA_ERROR_MSGQ_INVALID_ERR*：参数无效  
  *QOSA_ERROR_EVENT_SIZE_ERR*：消息大小与队列定义不符  
  *QOSA_ERROR_MSGQ_FULL_ERR*：消息队列已满，无法继续写入消息  
  *QOSA_ERROR_MSGQ_CREATE_ERR*：创建失败

### qosa_msgq_wait

- **功能描述**  
  从队列接收消息（消费者操作），支持超时等待。

- **函数原型**

```c
int qosa_msgq_wait(qosa_msgq_t msgQRef, qosa_uint8_t *value, qosa_uint32_t size, qosa_uint32_t timeout)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *msgQRef* | 输入 | qosa_msgq_t | 消息队列句柄 |
| *value* | 输入 | qosa_uint8_t * | 存储接收消息的缓冲区指针 |
| *size* | 输入 | qosa_uint32_t | 接收缓冲区的大小（必须与创建队列时指定的 *size* 一致） |
| *timeout* | 输入 | qosa_uint32_t | 等待超时时间。单位：毫秒<br>*QOSA_WAIT_FOREVER*：永久等待<br>*QOSA_NO_WAIT*：不等待 |

- **返回值说明**  
  *QOSA_ERROR_OK*：函数执行成功  
  *QOSA_ERROR_MSGQ_INVALID_ERR*：参数无效  
  *QOSA_ERROR_MSGQ_TIMEOUT_ERR*：操作等待超时  
  *QOSA_ERROR_MSGQ_RECV_ERR*：接收消息失败

### qosa_msgq_get_cnt

- **功能描述**  
  获取当前队列中的消息数量。

- **函数原型**

```c
int qosa_msgq_get_cnt(qosa_msgq_t msgQRef, qosa_uint32_t *cnt_ptr)
```

- **参数说明**

| **参数名** | **输入/输出** | **类型** | **说明** |
| --- | --- | --- | --- |
| *msgQRef* | 输入 | qosa_msgq_t | 消息队列句柄 |
| *cnt_ptr* | 输出 | qosa_uint32_t * | 存储消息数量的指针 |

- **返回值说明**  
  *QOSA_ERROR_OK*：函数执行成功  
  *QOSA_ERROR_MSGQ_INVALID_ERR*：参数无效

```{note}
1. 该函数返回的是调用瞬间的消息数量快照。
2. 在多任务环境下，获取到的消息数量在函数返回后可能立即发生变化。
```

## 枚举定义

### qosa_errcode_os_e

错误码枚举定义如下：

```c
typedef enum
{
    QOSA_ERROR_OK = 0,                                        
    ...
    QOSA_ERROR_MSGQ_CREATE_ERR = 1 | QOSA_ERRCODE_OS_BASE,    
    QOSA_ERROR_MSGQ_FULL_ERR,                                 
    QOSA_ERROR_MSGQ_RECV_ERR,                                
    QOSA_ERROR_MSGQ_TIMEOUT_ERR,                              
    QOSA_ERROR_MSGQ_INVALID_ERR,                              
    QOSA_ERROR_MSGQ_DELETE_ERR,                               
    QOSA_ERROR_MSGQ_RESET_ERR,                               
    ...
}qosa_errcode_os_e;
```

| **成员** | **说明** |
| --- | --- |
| *QOSA_ERROR_OK* | 函数执行成功 |
| *QOSA_ERROR_MSGQ_CREATE_ERR* | 创建失败 |
| *QOSA_ERROR_MSGQ_FULL_ERR* | 消息队列已满，无法继续写入消息 |
| *QOSA_ERROR_MSGQ_RECV_ERR* | 接收消息失败 |
| *QOSA_ERROR_MSGQ_TIMEOUT_ERR* | 操作等待超时 |
| *QOSA_ERROR_MSGQ_INVALID_ERR* | 参数无效 |
| *QOSA_ERROR_MSGQ_DELETE_ERR* | 删除失败 |
| *QOSA_ERROR_MSGQ_RESET_ERR* | 重置失败 |

# 应用逻辑流程图

```{figure} images/board_H1jkwr3eJhgPs7bnM4dcOqMynxg.jpg
:align: center
:alt: image
```

# 示例代码

完整示例代码请查看 https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/system/sync_comm/queue/messque_demo.c 。