Event Handling
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
◆ 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