xMessageBufferReceive()
[RTOS 消息缓冲区 API]

message_buffer.h

size_t xMessageBufferReceive( MessageBufferHandle_t xMessageBuffer,
                              void *pvRxData,
                              size_t xBufferLengthBytes,
                              TickType_t xTicksToWait );

从RTOS 消息缓冲区接收离散消息。 消息长度可变， 并且从缓冲区中复制出来。

注意： 与其他 FreeRTOS 对象都不同的是，流缓冲区的实现 （消息缓冲区的实现也是如此，因为消息缓冲区是建立在流缓冲区之上的） 流缓冲区的实现假定只有一个任务或中断将写入缓冲区（写入程序）， 缓冲区（写入器），只有一个任务或中断会从 （读取程序）。 写入和读取 不同的任务或中断是安全的，但与其他FreeRTOS对象不同， 有多个不同的写入或多个不同的读取是不安全的。 如果 必须有多个不同的写入，那么应用程序编写者必须 将每个调用放置到临界区中的一个写入 API 函数（如 xStreamBufferSend()）中， 并将发送阻塞时间设置为0。 同样，如果有多个不同的读取器， 那么应用程序编写者必须将每个调用放置到临界区中的读取API函数（如xStreamBufferRead()）中， 并使用接收阻塞时间 0。

使用 xMessageBufferReceive () 从任务中的消息缓冲区读取数据。 使用 xMessageBufferReceiveFromISR() 从 中断服务程序 (ISR) 中的消息缓冲区读取数据。

消息缓冲区的功能是通过将 FreeRTOS/source/stream_buffer.c 源文件包含在构建中 来启用消息缓冲区功能（因为消息缓冲区使用流缓冲区）。

参数：

xMessageBuffer	正在接收消息来自的消息缓冲区 的句柄。
pvRxData	指向缓冲区的指针，收到的信息 将被复制到该缓冲区。
xBufferLengthBytes	由 pvRxData 参数指向的缓冲区的 长度。 这将设置可以接收的消息的最大长度。 如果 xBufferLengthBytes 空间不足，无法保存下一条消息，那么消息 将保留在消息缓冲区中，并且将返回 0。
xTicksToWait	调用xMessageBufferReceive()时， 如果消息缓冲区为空， 则调用任务保持在阻塞状态等待消息的最长时间。 如果 xTicksToWait 为零并且消息缓冲区为空，将立即返回。 阻塞时间在滴答周期中指定，因此 它所表示的绝对时间取决于滴答频率。 宏pdMS_TO_TICKS()可以用来将以毫秒为单位的时间转换成以刻度为单位的时间。 宏pdMS_TO_TICKS()可以用来将以毫秒为单位的时间 转换为以 tick 为单位的时间。 将xTicksToWait设置为portMAX_DELAY会 导致任务无限期地等待（没有超时），前提是 在FreeRTOSConfig.h中将INCLUDE_vTaskSuspend设置为1。 任务在处于阻塞状态时 在处于已阻塞状态时不使用任何 CPU 时间。

返回：

从消息缓冲区读取的消息的长度（以字节为单位） （如有）。 如果在消息写入之前，xMessageBufferSend() 调用超时， 则返回零。 如果消息长度大于 xBufferLengthBytes，则消息将保留在消息缓冲区中， 同时返回零。

用法示例：

void vAFunction( MessageBuffer_t xMessageBuffer )
{
uint8_t ucRxData[ 20 ];
size_t xReceivedBytes;
const TickType_t xBlockTime = pdMS_TO_TICKS( 20 );

    /* Receive the next message from the message buffer.  Wait in the Blocked
    state (so not using any CPU processing time) for a maximum of 100ms for
    a message to become available. */
    xReceivedBytes = xMessageBufferReceive( xMessageBuffer,
                                            ( void * ) ucRxData,
                                            sizeof( ucRxData ),
                                            xBlockTime );

    if( xReceivedBytes > 0 )
    {
        /* A ucRxData contains a message that is xReceivedBytes long.  Process
        the message here.... */
    }
}