xEventGroupWaitBits()
[事件组 API]

event_groups.h

 EventBits_t xEventGroupWaitBits(
                       const EventGroupHandle_t xEventGroup,
                       const EventBits_t uxBitsToWaitFor,
                       const BaseType_t xClearOnExit,
                       const BaseType_t xWaitForAllBits,
                       TickType_t xTicksToWait );

读取 RTOS 事件组中的位，选择性地进入“已阻塞”状态（已设置 超时值）以等待设置单个位或一组位。

无法从中断调用此函数。

要使 xEventGroupWaitBits() 函数可用，RTOS 源文件 FreeRTOS/source/event_groups.c 必须 包含在构建中。

参数：

xEventGroup	正在测试位的事件组。 此前 必须已通过 xEventGroupCreate() 创建好事件组。
uxBitsToWaitFor	指定事件组中要测试的一个或多个事件位 的按位值。 例如，要等待第 0 位和/或第 2 位， 请将 uxBitsToWaitFor 设置为 0x05。 要等待第 0 位和/或第 1 位和/或第 2 位， 请设置 uxBitsToWaitFor 为 0x07， 以此类推。 uxBitsToWaitFor 不得设置为 0。
xClearOnExit	如果 xClearOnExit 设置为 pdTRUE， 那么在作为 uxBitsToWaitFor 参数传递的值中设置的任何位 会在 xEventGroupWaitBits() 返回某个值之前在事件组中清除掉， 前提是 xEventGroupWaitBits() 因超时以外的原因而返回值 。 超时值由 xTicksToWait 参数设置。 如果 xClearOnExit 设置为 pdFALSE， 那么当调用 xEventGroupWaitBits() 返回时，事件组中设置的位不会改变。
xWaitForAllBits	xWaitForAllBits 用于创建逻辑与测试 （必须设置所有位）或逻辑或测试（必须设置一个 或多个位），如下所示： 如果 xWaitForAllBits 设置为 pdTRUE， 那么当在作为 uxBitsToWaitFor 参数传递的值中设置的所有位 均已在事件组中设置好，或指定的阻塞时间已过期，则 xEventGroupWaitBits() 会返回相应值。 如果 xWaitForAllBits 设置为 pdFALSE，那么当在作为 uxBitsToWaitFor 参数传递的值中设置的任何位已在事件组中设置好， 或指定的阻塞时间已过期，则 xEventGroupWaitBits() 会返回相应值。
xTicksToWait	等待 uxBitsToWaitFor 指定的一个/所有（取决于 xWaitForAllBits 的值）位完成设置的最大时间 （单位：tick）。

返回：

事件位等待完成设置或阻塞时间过期时 的事件组值。 如果 高优先级任务或中断在调用任务解除“已阻塞”状态和退出 xEventGroupWaitBits() 函数之间更改了事件位的值， 则事件组中事件位的当前值将与返回值不同 。

测试返回值以确定 哪些位已完成设置。 如果 xEventGroupWaitBits() 因为超时值过期而返回， 则并非在等待的所有位都会进行设置。 如果 xEventGroupWaitBits() 因为它所等待的位均已完成设置而返回相应值， 则返回值是自动清除 （原因是 xClearOnExit 参数设置为 pdTRUE）任何位之前的事件组值。

#define BIT_0	( 1 << 0 )
#define BIT_4	( 1 << 4 )

void aFunction( EventGroupHandle_t xEventGroup )
{
EventBits_t uxBits;
const TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;

  /* Wait a maximum of 100ms for either bit 0 or bit 4 to be set within
  the event group.  Clear the bits before exiting. */
  uxBits = xEventGroupWaitBits(
            xEventGroup,   /* The event group being tested. */
            BIT_0 | BIT_4, /* The bits within the event group to wait for. */
            pdTRUE,        /* BIT_0 & BIT_4 should be cleared before returning. */
            pdFALSE,       /* Don't wait for both bits, either bit will do. */
            xTicksToWait );/* Wait a maximum of 100ms for either bit to be set. */

  if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
  {
      /* xEventGroupWaitBits() returned because both bits were set. */
  }
  else if( ( uxBits & BIT_0 ) != 0 )
  {
      /* xEventGroupWaitBits() returned because just BIT_0 was set. */
  }
  else if( ( uxBits & BIT_4 ) != 0 )
  {
      /* xEventGroupWaitBits() returned because just BIT_4 was set. */
  }
  else
  {
      /* xEventGroupWaitBits() returned because xTicksToWait ticks passed
      without either BIT_0 or BIT_4 becoming set. */
  }
}