Chapter 2. API Reference
esp_err_t esp_event_loop_run(esp_event_loop_handle_t event_loop, TickType_t ticks_to_run)
Dispatch events posted to an event loop.
This function is used to dispatch events posted to a loop with no dedicated task, i.e task name was set to NULL
in event_loop_args argument during loop creation. This function includes an argument to limit the amount
of time it runs, returning control to the caller when that time expires (or some time afterwards). There is no
guarantee that a call to this function will exit at exactly the time of expiry. There is also no guarantee that
events have been dispatched during the call, as the function might have spent all of the alloted time waiting on
the event queue. Once an event has been unqueued, however, it is guaranteed to be dispatched. This guarantee
contributes to not being able to exit exactly at time of expiry as (1) blocking on internal mutexes is necessary
for dispatching the unqueued event, and (2) during dispatch of the unqueued event there is no way to control the
time occupied by handler code execution. The guaranteed time of exit is therefore the alloted time + amount
of time required to dispatch the last unqueued event.
In cases where waiting on the queue times out, ESP_OK is returned and not ESP_ERR_TIMEOUT, since it
is normal behavior.
Note encountering an unknown event that has been posted to the loop will only generate a warning, not an
error.
Return
• ESP_OK: Success
• Others: Fail
Parameters
• [in] event_loop: event loop to dispatch posted events from, must not be NULL
• [in] ticks_to_run: number of ticks to run the loop
esp_err_t esp_event_handler_register(esp_event_base_t event_base, int32_t event_id,
esp_event_handler_t event_handler, void
*event_handler_arg)
Register an event handler to the system event loop (legacy).
This function can be used to register a handler for either: (1) specific events, (2) all events of a certain event
base, or (3) all events known by the system event loop.
Note This function is obsolete and will be deprecated soon, please use esp_event_handler_instance_register()
instead.
• specific events: specify exact event_base and event_id
• all events of a certain base: specify exact event_base and use ESP_EVENT_ANY_ID as the event_id
• all events known by the loop: use ESP_EVENT_ANY_BASE for event_base and
ESP_EVENT_ANY_ID as the event_id
Registering multiple handlers to events is possible. Registering a single handler to multiple events is also
possible. However, registering the same handler to the same event multiple times would cause the previous
registrations to be overwritten.
Note the event loop library does not maintain a copy of event_handler_arg, therefore the user should ensure
that event_handler_arg still points to a valid location by the time the handler gets called
Return
• ESP_OK: Success
• ESP_ERR_NO_MEM: Cannot allocate memory for the handler
• ESP_ERR_INVALID_ARG: Invalid combination of event base and event id
• Others: Fail
Parameters
• [in] event_base: the base id of the event to register the handler for
• [in] event_id: the id of the event to register the handler for
• [in] event_handler: the handler function which gets called when the event is dispatched
• [in] event_handler_arg: data, aside from event data, that is passed to the handler when it
is called
Espressif Systems 839
Submit Document Feedback
Release v4.4
To Next Page
Loading...
Need help?
General