事件event

tos_event_create

  1. k_err_t tos_event_create(k_event_t *event, k_event_flag_t init_flag);
  • 功能描述

创建一个事件。

  • 参数解释

IN/OUT参数名描述[in]event事件句柄[in]init_flag事件初始旗标

  • 返回值

K_ERR_NONE 事件创建成功。

K_ERR_OBJ_PTR_NULL event指针为空。

tos_event_destroy

  1. k_err_t tos_event_destroy(k_event_t *event);
  • 功能描述

销毁一个事件。

  • 参数解释

IN/OUT参数名描述[in]event事件句柄

  • 返回值

K_ERR_NONE 事件销毁成功。

K_ERR_OBJ_PTR_NULL event指针为空。

K_ERR_OBJ_INVALID event指向的不是一个合法的事件。

tos_event_pend

  1. k_err_t tos_event_pend(k_event_t *event, k_event_flag_t flag_expect, k_event_flag_t *flag_match, k_tick_t timeout, k_opt_t opt);
  • 功能描述

尝试获取一个特定的事件。

  • 参数解释

IN/OUT参数名描述[in]event事件句柄[in]flag_expect期望获取到的事件旗标[out]flag_match实际获取到的事件旗标[in]timeout等待超时参数[in]opt选项

  • 注意

opt选项说明：

1、TOS_OPT_EVENT_PEND_ANY

​尝试从事件中获取一组旗标，并且这一组旗标包含flag_expect中标识的任意一个旗标，如果在此场景下视作event获取成功，则opt传递此参数。

​举例来说，如果传入的flag_expect为0x9（0x8 | 0x1），且opt为TOS_OPT_EVENT_PEND_ANY，则event包含的旗标包含0x8或者0x1即视为事件获取成功，也就是说，event包含的旗标为(0x8 | X, X为整数，且X∈(0, 0xFFFFFFFF])，或者(0x1 | X, X为整数，且X∈(0, 0xFFFFFFFF])。

2、TOS_OPT_EVENT_PEND_ALL

​尝试从事件中获取一组旗标，并且这一组旗标必须至少包含flag_expect中标识的所有旗标，如果只在此种场景下视作event获取成功，则opt传递此参数。

​举例来说，如果传入的flag_expect为0x9（0x8 | 0x1），且opt为TOS_OPT_EVENT_PEND_ALL，则event包含的旗标至少为0x9的最小全集才视为事件获取成功，也就是说，event包含的旗标应为(0x9 | X, X为整数，且X∈(0, 0xFFFFFFFF])。

3、TOS_OPT_EVENT_PEND_CLR

​如果希望读取完事件后，直接复位清空event的所有旗标，则opt传递此参数。

​举例来说，原event包含旗标为0x9，在传递TOS_OPT_EVENT_PEND_CLR参数并成功获取event中的旗标后，event包含的旗标会复位为0x0。

​如果希望一次传入多个选项，可以用逻辑“或”将多个参数连接传入，譬如同时希望采用TOS_OPT_EVENT_PEND_ANY 语义及TOS_OPT_EVENT_PEND_CLR，可以传入（TOS_OPT_EVENT_PEND_ANY | TOS_OPT_EVENT_PEND_CLR）。

​需要注意的是，不可以同时传入TOS_OPT_EVENT_PEND_ANY与TOS_OPT_EVENT_PEND_ALL。

  • 返回值

K_ERR_NONE 读取特定的事件成功。

K_ERR_EVENT_PEND_OPT_INVALID opt参数非法。

K_ERR_PEND_NOWAIT 未能从event中获取到期望的旗标，并且timeout参数为TOS_TIME_NOWAIT（表示未获取到期望旗标时立即返回）。

K_ERR_PEND_SCHED_LOCKED 未能从event中获取到期望的旗标，并且系统调度处于锁定的状态。

K_ERR_PEND_TIMEOUT 在超时范围内未能从event中获取到期望的旗标。

K_ERR_PEND_DESTROY 尝试获取旗标的事件被销毁了（tos_event_destroy）。

tos_event_post

  1. k_err_t tos_event_post(k_event_t *event, k_event_flag_t flag);
  • 功能描述

向事件中放置一组旗标

  • 参数解释

IN/OUT参数名描述[in]event事件句柄[in]flag要放置的旗标

  • 注意

调用此接口放置一组旗标时，原event中包含的旗标将被覆盖。

举例来说，如果原事件的旗标为0x1，并且要放置的旗标为0x8，此接口调用结束后，事件的旗标将被覆写为0x8。

  • 返回值

K_ERR_NONE 旗标放置成功。

K_ERR_OBJ_PTR_NULL event为空指针。

K_ERR_OBJ_INVALID event指向的并不是一个合法的事件。

tos_event_post_keep

  1. k_err_t tos_event_post_keep(k_event_t *event, k_event_flag_t flag);
  • 功能描述

向事件中放置一组旗标，原event中包含的旗标将被保留。

举例来说，如果原事件的旗标为0x1，并且要放置的旗标为0x8，此接口调用结束后，事件的旗标将被修改为0x9(0x8 | 0x1)，也就是说，原事件的包含的旗标被保留。

  • 参数解释

IN/OUT参数名描述[in]event事件句柄[in]flag要放置的旗标

  • 返回值

K_ERR_NONE 旗标放置成功。

K_ERR_OBJ_PTR_NULL event为空指针。

K_ERR_OBJ_INVALID event指向的并不是一个合法的事件。