14.2.3.4.2 Event Management

Events are used throughout the stack and may also be employed by the application. The application may add its own handlers to be executed upon events used by the stack.

Events used by the stack are defined in the firmware\src\config\default\zigbee\lib\inc\systemenvironment\include\sysEvents.h file. The maximum number of events that may be supported by the System Environment component is given by SYS_MAX_EVENTS. Each event may have several subscribers (handlers) associated with callback functions called one by one when the event is raised.

To subscribe to event call the SYS_SubscribeToEvent() function, supplying event ID of the SYS_EventId_t type and the pointer to instance of the SYS_EventReceiver_t type. The latter instance must be defined statically (or globally). The func field of the instance is set to the pointer to a callback function, which is executed when the event is raised. For example:

//The callback function for the event
static void eventCallback(SYS_EventId_t eventId, SYS_EventData_t data)
{
  ...
}

//Defined globally
 SYS_EventReceiver_t eventReceiver = { .func = eventCallback };

...
//Subscribe to the event with the EVENT_ID identifier. substitute with any
//ID code from the BcEvents_t enumeration
 SYS_SubscribeToEvent()(EVENT_ID, &eventReceiver);

Once a subscriber is added to the event, associating a callback function with it, the event may be raised by calling the SYS_PostEventfunction. The function is supplied with the event's ID (the first argument) and arbitrary data of the SYS_EventData_ttype (the second argument), which is passed to the event's callback function as the callback's data argument. If no data shall be passed to the callback set the second argument to 0. See the types of data passed with events within BcEvents_t enumeration's description. To pass the pointer to a structure, cast the pointer to the uintptr_t type. For example:

//The SYS_EventData_t_t type is supposed to be a type specific to the event that is raised
static SYS_EventData_t eventData;
...
SYS_PostEvent(EVENT_ID, (uintptr_t)&eventData);

A handler may be removed from an event by calling the SYS_UnsubscribeFromEvent()function, supplying it with the same values that were passed to SYS_SubscribeToEvent() function when the handler was added to the event. It is also possible to check if an event has any subscribers - call the SYS_IsEventDeliverable() function - and to check if a given receiver instance (of the SYS_EventReceiver_t type) was subscribed to a given event.