Event Handling

This contains all functionality needed to register/unregister event handlers. More...

Modules

Types
Event data types.
 
Macros
Event macros.
 

Functions

zos_result_t zn_event_issue (zos_event_handler_t handler, void *arg, zos_event_flag_t flags)
 Register an event to execute immediately then automatically unregister. More...
 
zos_result_t zn_event_register_timed (zos_event_handler_t handler, void *arg, uint32_t timeout_ms, zos_event_flag_t flags)
 Register event handler to execute after specified timeout. More...
 
zos_result_t zn_event_register_periodic (zos_event_handler_t handler, void *arg, uint32_t period_ms, zos_event_flag_t flags)
 Register event handler to execute every specified number of milliseconds. More...
 
zos_result_t zn_event_update_periodic (zos_event_handler_t handler, void *arg, uint32_t period_ms, zos_event_flag_t run_now_flag)
 Update a periodic event's execution period. More...
 
zos_result_t zn_event_unregister (zos_event_handler_t handler, void *arg)
 Unregister a pending event handler. More...
 
zos_result_t zn_event_unregister_all (zos_event_handler_t handler)
 Unregister all events with specified handler regardless of argument. More...
 
zos_result_t zn_event_restart (zos_event_handler_t handler, void *arg)
 Restart a timed/periodic event's timeout Refer to Registering/Unregistering Events for more information about registering/unregistering. More...
 
zos_result_t zn_event_trigger (zos_event_handler_t handler, void *arg)
 Force a timed/periodic event to execute immediately. More...
 
zos_bool_t zn_event_is_registered (zos_event_handler_t handler, void *arg)
 Indicates if an event has previously been registered. More...
 
zos_result_t zn_event_enable_irq_events (uint16_t max_count)
 Enable issuing events from an IRQ callback. More...
 
void zn_event_disable_irq_events (void)
 Free memory allocated by zn_event_enable_irq_events() More...
 
zos_bool_t zn_event_irq_events_enabled (void)
 Return if IRQ events have been enabled. More...
 
zos_result_t zn_event_register_failure_callback (zos_event_handler_t handler, zos_event_failure_callback_t callback)
 Register callback to be called if the event fails to execute. More...
 

Detailed Description

This contains all functionality needed to register/unregister event handlers.

Registering/Unregistering Events

When an event handler is registered both a function pointer and argument pointer are supplied. If the argument pointer is NULL then the function pointer is checked to ensure it has not previously been registered. The registration will fail if it's duplicate (and the ZOS_EVENT_FLAG_ALLOW_DUPLICATE is not set). If the argument pointer is not NULL, then both the function pointer AND argument pointer are checked for uniqueness. If no other function pointer and corresponding argument pointer have been registered then they'll be registered as a pair. This allows for the same event handler function pointer to be registered with different argument pointers

Likewise, when unregistering a function pointer and argument pointer are supplied. Again if the argument pointer is NULL then only the function pointer is used to find a match. If the argument pointer is not NULL then both the event handler function pointer AND argument pointer are used to find a match.

Function Documentation

void zn_event_disable_irq_events ( void  )

Free memory allocated by zn_event_enable_irq_events()

After this is called, zn_event_issue_from_irq() will no longer work.

Returns
zos_result_t result of api call
zos_result_t zn_event_enable_irq_events ( uint16_t  max_count)

Enable issuing events from an IRQ callback.

This allows for issuing events from an IRQ callback such as those registered by: zn_gpio_irq_enable() or zn_uart_register_rx_callback().

This should be called before zn_event_issue_from_irq() may be used.

Calling this API consumes additional RAM. Call zn_event_disable_irq_events() to free the memory used by this feature.

Parameters
max_countThe maximum number of queued events
Returns
zos_result_t result of api call
zos_bool_t zn_event_irq_events_enabled ( void  )

Return if IRQ events have been enabled.

zos_bool_t zn_event_is_registered ( zos_event_handler_t  handler,
void *  arg 
)

Indicates if an event has previously been registered.

Parameters
[in]handlerPointer to event handler
[in]argArgument pointer that was used when registering the handler
Returns
zos_result_t result of api call
zos_result_t zn_event_issue ( zos_event_handler_t  handler,
void *  arg,
zos_event_flag_t  flags 
)

Register an event to execute immediately then automatically unregister.

Note
By default the event handler will execute in the ZAP thread. Use the ZOS_EVENT_FLAG_SYS_EVENT_THREAD flag to have the event execute in the system event thread.

Refer to Registering/Unregistering Events for more information about registering/unregistering.

Parameters
[in]handlerPointer to event handler
[in]argArgument pointer that was used when registering the handler
[in]flagsOptional flags for the event, zos_event_flag_t
Returns
zos_result_t result of api call
Examples:
basic/ftp_upload/ftp_upload.c, basic/http_stream/http_stream.c, basic/tcp_client/tcp_client.c, basic/uart/uart.c, basic/websocket_client/websocket_client.c, cloud/bluemix/bluemix.c, cloud/mqttdemo/commands.c, cloud/simplemq/main.c, demo/pong/game_server.c, demo/pong/link_client.c, demo/uart_blaster/uart_blaster.c, nxp/lcd_scan/main.c, nxp/nfc3d/cloud_websocket.c, sensors/accel_interrupt/main.c, and sensors/range_finder/main.c.
zos_result_t zn_event_register_failure_callback ( zos_event_handler_t  handler,
zos_event_failure_callback_t  callback 
)

Register callback to be called if the event fails to execute.

Register a callback to be executed if an event fails to execute. This is particularly useful if the argument the event was registered with needs to be cleaned up.

Note
Failure to execute is different than failure to register. Failure to execute occurrs AFTER the event was registered. i.e. The event was successfully registered with zn_event_issue() , zn_event_register_timed() , zn_event_update_periodic() but failed to execute when the event was next in the execution queue.

An event will fail to execute if:

Note
This API may be called multiple times with the same handler argument. The last callback to be registered will be used.
Parameters
[in]handlerEvent handler to register failure callback with, the event handler does NOT need to be currently registered
[in]callbackCallback to be called if given handler failures to execute
Returns
zos_result_t result of api call
zos_result_t zn_event_register_periodic ( zos_event_handler_t  handler,
void *  arg,
uint32_t  period_ms,
zos_event_flag_t  flags 
)

Register event handler to execute every specified number of milliseconds.

Note
By default the event handler will execute in the ZAP thread. Use the ZOS_EVENT_FLAG_SYS_EVENT_THREAD flag to have the event execute in the system event thread.

Refer to Registering/Unregistering Events for more information about registering/unregistering.

Parameters
[in]handlerPointer to event handler
[in]argArgument to pass to event handler
[in]period_msPeriod in milliseconds for event handler to execute
[in]flagsOptional flags for the event, zos_event_flag_t
Returns
zos_result_t result of api call
Examples:
basic/blinky/blinky.c, basic/ftp_upload/ftp_upload.c, basic/log_file/log_file.c, basic/scan/scan.c, basic/system_monitor/system_monitor.c, basic/tcp_client/tcp_client.c, basic/udp_client/udp_client.c, basic/websocket_client/websocket_client.c, cloud/s2cdemo/zentri_platform_streams.c, demo/accelerometer_stream/accelerometer_stream.c, demo/gps/main.c, demo/moray3d/moray3d.c, nxp/nfc3d/cloud_rest.c, nxp/nfc3d/cloud_websocket.c, nxp/nfc3d/local.c, nxp/nxp3d/nxp3d.c, sensors/accelerometer/main.c, sensors/custom_driver/main.c, sensors/custom_sensors/main.c, sensors/gyroscope/main.c, sensors/hygrometer/main.c, sensors/io_expander/io_expander.c, sensors/magnetometer/main.c, sensors/skink/main.c, and sensors/thermometer/main.c.
zos_result_t zn_event_register_timed ( zos_event_handler_t  handler,
void *  arg,
uint32_t  timeout_ms,
zos_event_flag_t  flags 
)

Register event handler to execute after specified timeout.

Once the event executes it is automatically unregistered.

Note
By default the event handler will execute in the ZAP thread. Use the ZOS_EVENT_FLAG_SYS_EVENT_THREAD flag to have the event execute in the system event thread.

Refer to Registering/Unregistering Events for more information about registering/unregistering.

Parameters
[in]handlerPointer to event handler
[in]argArgument to pass to event handler
[in]timeout_msTime in milliseconds to wait before handler executes
[in]flagsOptional flags for the event, zos_event_flag_t
Returns
zos_result_t result of api call
Examples:
basic/tcp_client/tcp_client.c, basic/websocket_client/websocket_client.c, cloud/ble2bluemix/scan.c, cloud/bluemix/bluemix.c, cloud/simplemq/main.c, demo/pong/game.c, demo/pong/game_server.c, demo/pong/link_client.c, demo/uart_blaster/uart_blaster.c, nxp/lcd_scan/main.c, and nxp/nfc3d/cloud_websocket.c.
zos_result_t zn_event_restart ( zos_event_handler_t  handler,
void *  arg 
)

Restart a timed/periodic event's timeout Refer to Registering/Unregistering Events for more information about registering/unregistering.

Parameters
[in]handlerPointer to event handler
[in]argArgument pointer that was used when registering the handler
Returns
zos_result_t result of api call
zos_result_t zn_event_trigger ( zos_event_handler_t  handler,
void *  arg 
)

Force a timed/periodic event to execute immediately.

Refer to Registering/Unregistering Events for more information about registering/unregistering.

Parameters
[in]handlerPointer to event handler
[in]argArgument pointer that was used when registering the handler
Returns
zos_result_t result of api call
Examples:
nxp/nfc3d/cloud_websocket.c.
zos_result_t zn_event_unregister_all ( zos_event_handler_t  handler)

Unregister all events with specified handler regardless of argument.

zos_result_t zn_event_update_periodic ( zos_event_handler_t  handler,
void *  arg,
uint32_t  period_ms,
zos_event_flag_t  run_now_flag 
)

Update a periodic event's execution period.

Refer to Registering/Unregistering Events for more information about registering/unregistering.

Parameters
[in]handlerPointer to event handler
[in]argArgument to pass to event handler
[in]period_msPeriod in milliseconds for event handler to execute
[in]run_now_flagspecify ZOS_EVENT_FLAG_RUN_NOW to execute the event immediately, all other flags ignored
Returns
zos_result_t result of api call
Examples:
demo/accelerometer_stream/accelerometer_stream.c, demo/gps/main.c, demo/moray3d/moray3d.c, nxp/nfc3d/local.c, nxp/nxp3d/nxp3d.c, and sensors/skink/main.c.