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

Modules
Types
Event data types.

Macros
Event macros.

Functions
gos_result_t	gos_event_issue ( gos_handler_t handler, void *arg, gos_event_flag_t flags)
	Register an event to execute immediately then automatically unregister. More...

gos_result_t	gos_event_register_timed ( gos_handler_t handler, void *arg, uint32_t timeout_ms, gos_event_flag_t flags)
	Register event handler to execute after specified timeout. Once the event executes it is automatically unregistered. More...

gos_result_t	gos_event_register_periodic ( gos_handler_t handler, void *arg, uint32_t period_ms, gos_event_flag_t flags)
	Register event handler to execute every specified number of milliseconds. More...

gos_result_t	gos_event_update_periodic ( gos_handler_t handler, void *arg, uint32_t period_ms, gos_event_flag_t run_now_flag)
	Update a periodic event's execution period. More...

gos_result_t	gos_event_unregister ( gos_handler_t handler, void *arg)
	Unregister a pending event handler. More...

gos_result_t	gos_event_unregister_all ( gos_handler_t handler)
	Unregister all events with specified handler regardless of argument. More...

gos_result_t	gos_event_restart ( gos_handler_t handler, void *arg)
	Restart a timed/periodic event's timeout Refer to Registering/Unregistering Events for more information about registering/unregistering. More...

gos_result_t	gos_event_trigger ( gos_handler_t handler, void *arg)
	Force a timed/periodic event to execute immediately. More...

bool	gos_event_is_registered ( gos_handler_t handler, void *arg)
	Indicates if an event has previously been registered. More...

gos_result_t	gos_event_enable_irq_events (uint16_t max_count)
	Enable issuing events from an IRQ callback. More...

void	gos_event_disable_irq_events (void)
	Free memory allocated by gos_event_enable_irq_events() More...

bool	gos_event_irq_events_enabled (void)
	Return if IRQ events have been enabled.

gos_result_t	gos_event_register_failure_callback ( gos_handler_t handler, gos_handler_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 GOS_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

◆ gos_event_disable_irq_events()

void gos_event_disable_irq_events ( void )

Free memory allocated by gos_event_enable_irq_events()

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

Returns: gos_result_t result of api call

◆ gos_event_enable_irq_events()

gos_result_t gos_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: gos_gpio_irq_enable() or gos_uart_register_rx_callback().

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

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

Parameters

max_count The maximum number of queued events

Returns: gos_result_t result of api call

Examples:: demo/uart_blaster/uart_blaster.c , network/tcp_multiclient/main.c , network/uart_tcp_client/main.c , system/uart/main.c , and test/uart_flow_control/main.c .

◆ gos_event_is_registered()

bool gos_event_is_registered	(	gos_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: gos_result_t result of api call

◆ gos_event_issue()

gos_result_t gos_event_issue	(	gos_handler_t	`handler,`
		void *	`arg,`
		gos_event_flag_t	`flags`
	)

Register an event to execute immediately then automatically unregister.

Note: By default the event handler will execute in the app thread. See gos_event_flag_t for the other available event contexts.

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, gos_event_flag_t

Returns: gos_result_t result of api call

Examples:: cloud/coap_demo/commands.c , cloud/dps_demo/main.c , demo/3d_demo/main.c , demo/accelerometer_stream/main.c , demo/secure_element/main.c , demo/uart_blaster/uart_blaster.c , dms/messages/main.c , dms/ota_update/main.c , hurricane/arducam/camera.c , hurricane/security_camera/camera.c , hurricane/security_camera/main.c , network/tcp_client/main.c , network/tcp_multiclient/main.c , network/uart_tcp_client/main.c , network/udp_client/main.c , network/websocket_client/main.c , and system/uart/main.c .

◆ gos_event_register_failure_callback()

gos_result_t gos_event_register_failure_callback	(	gos_handler_t	`handler,`
		gos_handler_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 gos_event_issue() , gos_event_register_timed() , gos_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 gos_event_unregister() or gos_event_unregister_all()
It has the event was registered with GOS_EVENT_FLAG_REQUIRE_WLAN and the WLAN interface is down
It has the event was registered with GOS_EVENT_FLAG_REQUIRE_SOFTAP and the SoftAP interface is down
It has the event was registered with GOS_EVENT_FLAG_REQUIRE_ETHERNET and the Ethernet interface is down
It has the event was registered with GOS_EVENT_FLAG_IN_NETWORK_WORKER 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: gos_result_t result of api call

◆ gos_event_register_periodic()

gos_result_t gos_event_register_periodic	(	gos_handler_t	`handler,`
		void *	`arg,`
		uint32_t	`period_ms,`
		gos_event_flag_t	`flags`
	)

Register event handler to execute every specified number of milliseconds.

Note: By default the event handler will execute in the app thread. See gos_event_flag_t for the other available event contexts.; This API is not allowed from an IRQ context.; The period_ms argument MUST be greater than 0.

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, gos_event_flag_t

Returns: gos_result_t result of api call

Examples:: file/log_file/main.c , file/log_file_encrypted/main.c , hurricane/blinky/main.c , hurricane/marble/main.c , hurricane/security_camera/sensor.c , hurricane/weatherstation/main.c , intro/blinky/main.c , network/http_server_stream/main.c , network/tcp_client/main.c , network/udp_client/main.c , network/websocket_client/main.c , peripheral/adc/main.c , system/core_dump/main.c , system/custom_commands/main.c , system/system_monitor/main.c , test/throughput/main.c , test/uart_flow_control/main.c , and wifi/wifi_scan/main.c .

◆ gos_event_register_timed()

gos_result_t gos_event_register_timed	(	gos_handler_t	`handler,`
		void *	`arg,`
		uint32_t	`timeout_ms,`
		gos_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 app thread. See gos_event_flag_t for the other available event contexts.

GOS_EVENT_FLAG_UPDATE_TIMEOUT may be used to update an already registered timed event. If this flag is specified and:

The event IS currently pending then the timeout will be updated
The event is NOT currently pending then the a new event with the given timeout will be registered

This API is not allowed from an IRQ context.

If the


          timeout_ms

is 0 or the GOS_EVENT_FLAG_RUN_NOW flag is set then this does the same thing as gos_event_issue() .

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, gos_event_flag_t

Returns: gos_result_t result of api call

Examples:: cloud/dps_demo/main.c , demo/3d_demo/main.c , demo/accelerometer_stream/main.c , demo/secure_element/main.c , demo/uart_blaster/uart_blaster.c , dms/messages/main.c , dms/ota_update/main.c , hurricane/security_camera/camera.c , hurricane/security_camera/main.c , network/tcp_client/main.c , network/uart_tcp_client/main.c , network/udp_client/main.c , network/websocket_client/main.c , and test/throughput/main.c .

◆ gos_event_restart()

gos_result_t gos_event_restart	(	gos_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: gos_result_t result of api call

◆ gos_event_trigger()

gos_result_t gos_event_trigger	(	gos_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: gos_result_t result of api call

Examples:: hurricane/security_camera/sensor.c .

◆ gos_event_unregister()

gos_result_t gos_event_unregister	(	gos_handler_t	`handler,`
		void *	`arg`
	)

Unregister a pending event handler.

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

Note: This does NOT unregister events pending in the IRQ event queue. i.e. Events issued from an IRQ context are NOT unregistered with this API.

Parameters

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

Returns: gos_result_t result of api call

Examples:: demo/3d_demo/main.c , demo/accelerometer_stream/main.c , demo/uart_blaster/uart_blaster.c , dms/messages/main.c , file/log_file/main.c , file/log_file_encrypted/main.c , hurricane/arducam/camera.c , hurricane/security_camera/camera.c , hurricane/security_camera/sensor.c , network/http_server_stream/main.c , network/tcp_client/main.c , network/uart_tcp_client/main.c , network/udp_client/main.c , network/websocket_client/main.c , system/custom_commands/main.c , system/system_monitor/main.c , test/throughput/main.c , and test/uart_flow_control/main.c .

◆ gos_event_unregister_all()

gos_result_t gos_event_unregister_all ( gos_handler_t handler )

Unregister all events with specified handler regardless of argument.

Note: This does NOT unregister events pending in the IRQ event queue. i.e. Events issued from an IRQ context are NOT unregistered with this API.

Parameters

[in] handler Pointer to event handler

Returns: gos_result_t result of api call

Examples:: hurricane/blinky/main.c , hurricane/marble/main.c , and hurricane/weatherstation/main.c .

◆ gos_event_update_periodic()

gos_result_t gos_event_update_periodic	(	gos_handler_t	`handler,`
		void *	`arg,`
		uint32_t	`period_ms,`
		gos_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 GOS_EVENT_FLAG_RUN_NOW to execute the event immediately, all other flags ignored

Returns: gos_result_t result of api call

Event Handling

Modules

Functions

Detailed Description

Registering/Unregistering Events

Function Documentation

◆ gos_event_disable_irq_events()

◆ gos_event_enable_irq_events()

◆ gos_event_is_registered()

◆ gos_event_issue()

◆ gos_event_register_failure_callback()

◆ gos_event_register_periodic()

◆ gos_event_register_timed()

◆ gos_event_restart()

◆ gos_event_trigger()

◆ gos_event_unregister()

◆ gos_event_unregister_all()

◆ gos_event_update_periodic()