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

message_buffer.h

size_t xMessageBufferReceiveFromISR( MessageBufferHandle_t xMessageBuffer,
                                     void *pvRxData,
                                     size_t xBufferLengthBytes,
                                     BaseType_t *pxHigherPriorityTaskWoken );

中断安全版本的 API 函数，用于 从消息缓冲区接收离散消息。 消息长度可变， 从缓冲区中复制出来。

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

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

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

参数：

xMessageBuffer	消息缓冲区的句柄，正在接收的信息来自该消息缓存区。
pvRxData	一个指向缓冲区的指针，收到的信息将 被复制到该缓冲区。
xBufferLengthBytes	由 pvRxData 参数指向的缓冲区的 长度。 这将设置可以接收的消息的最大长度。 如果 xBufferLengthBytes 空间不足，无法保存下一条消息，那么消息 将保留在消息缓冲区中，并且将返回 0。
pxHigherPriorityTaskWoken	（此为可选参数，可以设置为 NULL。） 消息缓冲区可能会 阻塞任务，等待可用空间。 调用 xMessageBufferReceiveFromISR () 可以使空间可用，从而使等待空间的任务 结束阻塞状态。 如果调用 xMessageBufferReceiveFromISR () 导致任务结束阻塞状态，并且 未阻塞任务的优先级高于当前正在执行的任务 （被中断的任务），那么在内部， xMessageBufferReceiveFromISR() 将* pxHigherPriorityTaskWoken 设置为 pdTRUE。 如果 xMessageBufferReceiveFromISR() 将此值设置为 pdTRUE， 那么通常应在退出中断之前执行上下文切换。 这将 确保中断直接返回到最高优先级的就绪状态 任务。 * pxHigherPriorityTaskWoken在传递给函数之前 应该设置为pdFALSE。 有关示例，请参阅下面的代码示例。

返回：

从消息缓冲区读取的消息的长度（以字节为单位） （如有）。

用法示例：

/* A message buffer that has already been created. */
MessageBuffer_t xMessageBuffer;

void vAnInterruptServiceRoutine( void )
{
uint8_t ucRxData[ 20 ];
size_t xReceivedBytes;
BaseType_t xHigherPriorityTaskWoken = pdFALSE;  /* Initialised to pdFALSE. */

    /* Receive the next message from the message buffer. */
    xReceivedBytes = xMessageBufferReceiveFromISR( xMessageBuffer,
                                                  ( void * ) ucRxData,
                                                  sizeof( ucRxData ),
                                                  &xHigherPriorityTaskWoken );

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

    /* If xHigherPriorityTaskWoken was set to pdTRUE inside
    xMessageBufferReceiveFromISR() then a task that has a priority above the
    priority of the currently executing task was unblocked and a context
    switch should be performed to ensure the ISR returns to the unblocked
    task.  In most FreeRTOS ports this is done by simply passing
    xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
    variables value, and perform the context switch if necessary.  Check the
    documentation for the port in use for port specific instructions. */
    taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}