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_count The 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]	`handler`	Pointer to event handler
[in]	`arg`	Argument 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]	`handler`	Pointer to event handler
[in]	`arg`	Argument pointer that was used when registering the handler
[in]	`flags`	Optional 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:

It is unregistered using zn_event_unregister() or zn_event_unregister_all()
It has the event was registered with ZOS_EVENT_FLAG_REQUIRE_WLAN and the WLAN interface is down
It has the event was registered with ZOS_EVENT_FLAG_REQUIRE_SOFTAP and the SoftAP interface is down
It has the event was registered with ZOS_EVENT_FLAG_NETWORK_THREAD but the Network Thread queue was full

Note: This API may be called multiple times with the same handler argument. The last callback to be registered will be used.

Parameters

[in]	`handler`	Event handler to register failure callback with, the event handler does NOT need to be currently registered
[in]	`callback`	Callback 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]	`handler`	Pointer to event handler
[in]	`arg`	Argument to pass to event handler
[in]	`period_ms`	Period in milliseconds for event handler to execute
[in]	`flags`	Optional 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]	`handler`	Pointer to event handler
[in]	`arg`	Argument to pass to event handler
[in]	`timeout_ms`	Time in milliseconds to wait before handler executes
[in]	`flags`	Optional 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/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]	`handler`	Pointer to event handler
[in]	`arg`	Argument 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]	`handler`	Pointer to event handler
[in]	`arg`	Argument 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	(	zos_event_handler_t	`handler,`
		void *	`arg`
	)

Unregister a pending event handler.

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

Parameters

[in]	`handler`	Pointer to event handler
[in]	`arg`	Argument pointer that was used when registering the handler

Returns: zos_result_t result of api call

Examples:: basic/ftp_upload/ftp_upload.c, basic/log_file/log_file.c, basic/system_monitor/system_monitor.c, basic/tcp_client/tcp_client.c, basic/websocket_client/websocket_client.c, cloud/s2cdemo/zentri_platform_streams.c, cloud/simplemq/main.c, demo/accelerometer_stream/accelerometer_stream.c, demo/gps/main.c, demo/moray3d/moray3d.c, demo/pong/game.c, demo/pong/game_server.c, demo/uart_blaster/uart_blaster.c, nxp/nfc3d/cloud_websocket.c, nxp/nfc3d/local.c, nxp/nxp3d/nxp3d.c, and sensors/skink/main.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]	`handler`	Pointer to event handler
[in]	`arg`	Argument to pass to event handler
[in]	`period_ms`	Period in milliseconds for event handler to execute
[in]	`run_now_flag`	specify 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.

Event Handling

Modules

Functions

Detailed Description

Registering/Unregistering Events

Function Documentation