4.4.2 Event Management

The stack and applications use events extensively, and applications can add their own handlers to execute when stack events occur.

The stack defines its events in the firmware\src\config\default\zigbee\lib\inc\systemenvironment\include\sysEvents.h file. The SYS_MAX_EVENTS constant specifies the maximum number of events the system environment component can support. An event can have multiple subscribers (handlers) with associated callback functions that the system calls sequentially when it raises the event.

To subscribe to the event, the user must call the SYS_SubscribeToEvent() function. Provide the event ID of the SYS_EventId_t type and a pointer to an instance of the SYS_EventReceiver_t type. The user must define this instance statically (or globally). Set the instance's func field to the pointer of a callback function to be 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);

After adding a subscriber to the event and associating a callback function with it, the user can raise the event by calling the SYS_PostEvent function. Provide the event’s ID as the first argument and arbitrary data of the SYS_EventData_t type as the second argument. This data is going to be passed to the event’s callback function as the data argument of the callback. If the user does not need to pass any data to the callback, set the second argument to ‘0’. The user can find the types of data passed with events in the description of the BcEvents_t enumeration. To pass a 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);

The user can remove a handler from an event by calling the SYS_UnsubscribeFromEvent() function, providing the same values that were originally passed to the SYS_SubscribeToEvent() function when adding the handler. In addition, the user can perform the following checks:

To determine if an event has any subscribers, call the SYS_IsEventDeliverable() function.
To verify if a specific receiver instance (of the SYS_EventReceiver_t type) is subscribed to an event, perform the necessary check.