FreeRTOS api库函数之Message Buffers（消息缓冲区）

xMessageBufferCreate（）
MessageBufferHandle_t xMessageBufferCreate（size_t xBufferSizeBytes）;

使用动态分配的内存创建新的消息缓冲区。有关使用静态分配的内存（在编译时分配的内存）的版本，请参阅xMessageBufferCreateStatic（）。
必须在FreeRTOSConfig.h中将configSUPPORT_DYNAMIC_ALLOCATION设置为1或未定义，才能使xMessageBufferCreate（）可用。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用消息缓冲区功能（作为消息缓冲区使用流缓冲区）。

参数：
    xBufferSizeBytes 消息缓冲区在任何时候都能保存的总字节数（而不是消息）。当消息写入消息缓冲区时，还会写入另外的sizeof（size_t）字节来存储消息的长度。 sizeof（size_t）在32位体系结构上通常为4个字节，因此在大多数32位体系结构中，10字节消息将占用14个字节的消息缓冲区空间。

返回：
    如果返回NULL，则无法创建消息缓冲区，因为FreeRTOS没有足够的堆内存来分配消息缓冲区数据结构和存储区域。返回的非NULL值表示已成功创建消息缓冲区 - 返回的值应存储为创建的消息缓冲区的句柄。

xMessageBufferCreateStatic（）
MessageBufferHandle_t xMessageBufferCreateStatic（
                                          size_t xBufferSizeBytes，
                                          uint8_t * pucMessageBufferStorageArea，
                                          StaticMessageBuffer_t * pxStaticMessageBuffer）;
使用静态分配的内存创建新的消息缓冲区。
FreeRTOSConfig.h中的configSUPPORT_STATIC_ALLOCATION必须设置为1才能使xMessageBufferCreateStatic（）可用。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用消息缓冲区功能（作为消息缓冲区使用流缓冲区）。
参数：
    xBufferSizeBytes  pucMessageBufferStorageArea参数指向的缓冲区的大小（以字节为单位）。当消息写入消息缓冲区时，还会写入另外的sizeof（size_t）字节来存储消息的长度。 sizeof（size_t）在32位体系结构上通常为4个字节，因此在大多数32位体系结构中，10字节消息将占用14个字节的消息缓冲区空间。可以存储在消息缓冲区中的最大字节数实际上（xBufferSizeBytes - 1）。
    pucMessageBufferStorageArea 必须指向至少xBufferSizeBytes + 1大的uint8_t数组。这是在将消息写入消息缓冲区时将消息复制到的数组。
    pxStaticMessageBuffer 必须指向StaticMessageBuffer_t类型的变量，该变量将用于保存消息缓冲区的数据结构。
返回：
    如果成功创建了消息缓冲区，则返回创建的消息缓冲区的句柄。如果pucMessageBufferStorageArea或pxStaticMessageBuffer为NULL，则返回NULL。

xMessageBufferSend（）
size_t xMessageBufferSend（MessageBufferHandle_t xMessageBuffer，
                           const void * pvTxData，
                           size_t xDataLengthBytes，
                           TickType_t xTicksToWait）;
将离散消息发送到消息缓冲区。消息可以是适合缓冲区可用空间的任何长度，并被复制到缓冲区中。
注意：在FreeRTOS对象中，流缓冲区实现（以及消息缓冲区实现，因为消息缓冲区构建在流缓冲区之上）假设只有一个任务或中断将写入缓冲区（写入程序），并且只有一个任务或中断将从缓冲区（阅读器）读取。作者和读者可以安全地处理不同的任务或中断，但与其他FreeRTOS对象不同，拥有多个不同的编写器或多个不同的读取器是不安全的。如果要有多个不同的编写器，那么应​​用程序编写者必须将每个调用放在一个临界区内的写API函数（例如xMessageBufferSend（））中，并使用0的发送块时间。同样，如果有多个不同的然后，应用程序编写者必须将每个调用放在一个关键部分内的读取API函数（例如xMessageBufferRead（））中，并使用接收块时间为0。
使用xMessageBufferSend（）从任务写入消息缓冲区。使用xMessageBufferSendFromISR（）从中断服务例程（ISR）写入消息缓冲区。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用消息缓冲区功能（作为消息缓冲区使用流缓冲区）。
参数：
    xMessageBuffer 正在向其发送消息的消息缓冲区的句柄。
    pvTxData 指向要复制到消息缓冲区中的消息的指针。
    xDataLengthBytes 消息的长度。也就是说，从pvTxData复制到消息缓冲区的字节数。当消息写入消息缓冲区时，还会写入另外的sizeof（size_t）字节来存储消息的长度。 sizeof（size_t）在32位体系结构上通常为4个字节，因此在大多数32位体系结构设置xDataLengthBytes为20时，会将消息缓冲区中的可用空间减少24个字节（20个字节的消息数据和4个字节来保存消息长度）。
    xTicksToWait xTicksToWait 调用xMessageBufferSend（）时，如果消息缓冲区空间不足，则调用任务应保持在阻塞状态以等待消息缓冲区中有足够空间可用的最长时间。如果xTicksToWait为零，则调用任务将永远不会阻塞。块时间在滴答周期中指定，因此它表示的绝对时间取决于滴答频率。宏pdMS_TO_TICKS（）可用于将以毫秒为单位指定的时间转换为刻度中指定的时间。如果在FreeRTOSConfig.h中将INCLUDE_vTaskSuspend设置为1，则将xTicksToWait设置为portMAX_DELAY将导致任务无限期地等待（没有超时）。任务在处于阻止状态时不使用任何CPU时间。
返回：
    写入消息缓冲区的字节数。如果在有足够的空间将消息写入消息缓冲区之前对xMessageBufferSend（）的调用超时，则返回零。如果调用没有超时，则返回xDataLengthBytes。

xMessageBufferSendFromISR（）
size_t xMessageBufferSendFromISR（MessageBufferHandle_t xMessageBuffer，const void * pvTxData，size_t xDataLengthBytes，BaseType_t * pxHigherPriorityTaskWoken）;
中断安全版本的API函数，用于向消息缓冲区发送离散消息。消息可以是适合缓冲区可用空间的任何长度，并被复制到缓冲区中。
注意：在FreeRTOS对象中，流缓冲区实现（以及消息缓冲区实现，因为消息缓冲区构建在流缓冲区之上）假设只有一个任务或中断将写入缓冲区（写入程序），并且只有一个任务或中断将从缓冲区（阅读器）读取。作者和读者可以安全地处理不同的任务或中断，但与其他FreeRTOS对象不同，拥有多个不同的编写器或多个不同的读取器是不安全的。如果要有多个不同的编写器，那么应​​用程序编写者必须将每个调用放在一个临界区内的写API函数（例如xMessageBufferSend（））中，并使用0的发送块时间。同样，如果有多个不同的然后，应用程序编写者必须将每个调用放在一个关键部分内的读取API函数（例如xMessageBufferRead（））中，并使用接收块时间为0。
使用xMessageBufferSend（）从任务写入消息缓冲区。使用xMessageBufferSendFromISR（）从中断服务例程（ISR）写入消息缓冲区。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用消息缓冲区功能（作为消息缓冲区使用流缓冲区）。
参数：
    xMessageBuffer 正在向其发送消息的消息缓冲区的句柄。
    pvTxData 指向要复制到消息缓冲区中的消息的指针。
    xDataLengthBytes 消息的长度。也就是说，从pvTxData复制到消息缓冲区的字节数。当消息写入消息缓冲区时，还会写入另外的sizeof（size_t）字节来存储消息的长度。 sizeof（size_t）在32位体系结构上通常为4个字节，因此在大多数32位体系结构设置xDataLengthBytes为20时，会将消息缓冲区中的可用空间减少24个字节（20个字节的消息数据和4个字节来保存消息长度）。
    pxHigherPriorityTaskWoken 消息缓冲区可能会阻塞任务等待数据。调用xMessageBufferSendFromISR（）可以使数据可用，从而导致正在等待数据离开阻塞状态的任务。如果调用xMessageBufferSendFromISR（）导致任务离开阻塞状态，并且未阻塞任务的优先级高于当前正在执行的任务（被中断的任务），则在内部，xMessageBufferSendFromISR（）将* pxHigherPriorityTaskWoken设置为pdTRUE。如果xMessageBufferSendFromISR（）将此值设置为pdTRUE，则通常应在退出中断之前执行上下文切换。这将确保中断直接返回到最高优先级的就绪状态任务。 * pxHigherPriorityTaskWoken在传递给函数之前应该设置为pdFALSE。有关示例，请参阅下面的代码示例。
返回：
    实际写入消息缓冲区的字节数。如果消息缓冲区没有足够的可用空间来存储消息，则返回0，否则返回xDataLengthBytes。

xMessageBufferReceive（）
size_t xMessageBufferReceive（MessageBufferHandle_t xMessageBuffer，void * pvRxData，size_t xBufferLengthBytes，TickType_t xTicksToWait）;
从RTOS消息缓冲区接收离散消息。消息可以是可变长度的，并从缓冲区中复制出来。
注意：在FreeRTOS对象中，流缓冲区实现（以及消息缓冲区实现，因为消息缓冲区构建在流缓冲区之上）假设只有一个任务或中断将写入缓冲区（写入程序），并且只有一个任务或中断将从缓冲区（阅读器）读取。作者和读者可以安全地处理不同的任务或中断，但与其他FreeRTOS对象不同，拥有多个不同的编写器或多个不同的读取器是不安全的。如果要有多个不同的编写器，那么应​​用程序编写者必须将每个调用放在一个临界区内的写API函数（例如xMessageBufferSend（））中，并使用0的发送块时间。同样，如果有多个不同的然后，应用程序编写者必须将每个调用放在一个关键部分内的读取API函数（例如xMessageBufferRead（））中，并使用接收块时间为0。
使用xMessageBufferReceive（）从任务中读取消息缓冲区。使用xMessageBufferReceiveFromISR（）从中断服务例程（ISR）读取消息缓冲区。

通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用消息缓冲区功能（作为消息缓冲区使用流缓冲区）。
参数：
    xMessageBuffer 从中接收消息的消息缓冲区的句柄。
    pvRxData 指向要将复制的消息复制到的缓冲区的指针。
    xBufferLengthBytes  pvRxData参数指向的缓冲区长度。这将设置可以接收的消息的最大长度。如果xBufferLengthBytes太小而无法保存下一条消息，则消息将保留在消息缓冲区中，并返回0。
    xTicksToWait 在调用xMessageBufferReceive（）时，如果消息缓冲区为空，则任务应保持在阻塞状态以等待消息的最长时间。如果xTicksToWait为零且消息缓冲区为空，则xMessageBufferReceive（）将立即返回。块时间在滴答周期中指定，因此它表示的绝对时间取决于滴答频率。宏pdMS_TO_TICKS（）可用于将以毫秒为单位指定的时间转换为刻度中指定的时间。如果在FreeRTOSConfig.h中将INCLUDE_vTaskSuspend设置为1，则将xTicksToWait设置为portMAX_DELAY将导致任务无限期地等待（没有超时）。任务在处于阻止状态时不使用任何CPU时间。
返回：
    从消息缓冲区读取的消息的长度（以字节为单位）（如果有）。如果xMessageBufferReceive（）在消息可用之前超时，则返回零。如果消息的长度大于xBufferLengthBytes，则消息将保留在消息缓冲区中并返回零。

xMessageBufferReceiveFromISR（）
size_t xMessageBufferReceiveFromISR（MessageBufferHandle_t xMessageBuffer，void * pvRxData，size_t xBufferLengthBytes，BaseType_t * pxHigherPriorityTaskWoken）;
API函数的中断安全版本，它从消息缓冲区接收离散消息。消息可以是可变长度的，并从缓冲区中复制出来。
注意：在FreeRTOS对象中，流缓冲区实现（以及消息缓冲区实现，因为消息缓冲区构建在流缓冲区之上）假设只有一个任务或中断将写入缓冲区（写入程序），并且只有一个任务或中断将从缓冲区（阅读器）读取。作者和读者可以安全地处理不同的任务或中断，但与其他FreeRTOS对象不同，拥有多个不同的编写器或多个不同的读取器是不安全的。如果要有多个不同的编写器，那么应​​用程序编写者必须将每个调用放在一个临界区内的写API函数（例如xMessageBufferSend（））中，并使用0的发送块时间。同样，如果有多个不同的然后，应用程序编写者必须将每个调用放在一个关键部分内的读取API函数（例如xMessageBufferRead（））中，并使用接收块时间为0。
使用xMessageBufferReceive（）从任务中读取消息缓冲区。使用xMessageBufferReceiveFromISR（）从中断服务例程（ISR）读取消息缓冲区。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用消息缓冲区功能（作为消息缓冲区使用流缓冲区）。
参数：
    xMessageBuffer 从中接收消息的消息缓冲区的句柄。
    pvRxData 指向将要复制接收消息的缓冲区的指针。
    xBufferLengthBytes  pvRxData参数指向的缓冲区长度。这将设置可以接收的消息的最大长度。如果xBufferLengthBytes太小而无法保存下一条消息，则消息将保留在消息缓冲区中，并返回0。
    pxHigherPriorityTaskWoken 消息缓冲区可能会阻塞任务，等待空间可用。调用xMessageBufferReceiveFromISR（）可以使空间可用，从而导致等待空间的任务离开阻塞状态。如果调用xMessageBufferReceiveFromISR（）导致任务离开阻塞状态，并且未阻塞任务的优先级高于当前正在执行的任务（被中断的任务），则在内部，xMessageBufferReceiveFromISR（）将* pxHigherPriorityTaskWoken设置为pdTRUE。如果xMessageBufferReceiveFromISR（）将此值设置为pdTRUE，则通常应在退出中断之前执行上下文切换。这将确保中断直接返回到最高优先级的就绪状态任务。 * pxHigherPriorityTaskWoken在传递给函数之前应该设置为pdFALSE。
返回：
    从消息缓冲区读取的消息的长度（以字节为单位）（如果有）。

vMessageBufferDelete（）
void vMessageBufferDelete（MessageBufferHandle_t xMessageBuffer）;
删除先前使用对xMessageBufferCreate（）或xMessageBufferCreateStatic（）的调用创建的消息缓冲区。 如果使用动态内存（即xMessageBufferCreate（））创建消息缓冲区，则释放分配的内存。
删除消息缓冲区后，不得使用消息缓冲区句柄。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用消息缓冲区功能（作为消息缓冲区使用流缓冲区）。
参数：
     xMessageBuffer 要删除的消息缓冲区的句柄。

xMessageBufferSpacesAvailable（）
size_t xMessageBufferSpacesAvailable（MessageBufferHandle_t xMessageBuffer）;
查询消息缓冲区以查看它包含多少可用空间，这等于可以在消息缓冲区满之前发送到消息缓冲区的数据量。返回值比可以发送到消息缓冲区的最大消息大小大4个字节。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用消息缓冲区功能（作为消息缓冲区使用流缓冲区）。
参数：
    xMessageBuffer 正在查询的消息缓冲区的句柄。
返回：
    在消息缓冲区满之前可以写入消息缓冲区的字节数。当消息写入消息缓冲区时，还会写入另外的sizeof（size_t）字节来存储消息的长度。 sizeof（size_t）在32位体系结构上通常为4个字节，因此如果xMessageBufferSpacesAvailable（）返回10，则可写入消息缓冲区的最大消息的大小为6个字节。

xMessageBufferReset（）
BaseType_t xMessageBufferReset（MessageBufferHandle_t xMessageBuffer）;
将消息缓冲区重置为其初始的空状态。 消息缓冲区中的所有数据都将被丢弃。 如果没有任何任务被阻止等待发送到消息缓冲区或从消息缓冲区接收，则只能重置消息缓冲区。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用消息缓冲区功能（作为消息缓冲区使用流缓冲区）。
参数：
     xMessageBuffer 正在重置的消息缓冲区的句柄。
返回：
     如果重置消息缓冲区，则返回pdPASS。 如果有任务被阻止等待发送到消息缓冲区或从消息缓冲区读取，则不会重置消息缓冲区并返回pdFAIL。

xMessageBufferIsEmpty（）
BaseType_t xMessageBufferIsEmpty（MessageBufferHandle_t xMessageBuffer）;
查询消息缓冲区以查看它是否为空。 如果消息缓冲区不包含任何消息，则该消息缓冲区为空。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用消息缓冲区功能（作为消息缓冲区使用流缓冲区）。
参数：
     xMessageBuffer 正在查询的消息缓冲区的句柄。
返回：
     如果消息缓冲区为空，则返回pdTRUE。 否则返回pdFALSE。

xMessageBufferIsFull（）
BaseType_t xMessageBufferIsFull（MessageBufferHandle_t xMessageBuffer）;
查询消息缓冲区以查看它是否已满。 如果消息缓冲区无法接受任何大小的消息，则消息缓冲区已满，直到从消息缓冲区中删除消息使空间可用。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用消息缓冲区功能（作为消息缓冲区使用流缓冲区）。
参数：
     xMessageBuffer 正在查询的消息缓冲区的句柄。
返回：
     如果消息缓冲区已满，则返回pdTRUE。 否则返回pdFALSE。