Retrieves the next event from the application's active channel.
BPS_API int bps_get_event(bps_event_t **event, int timeout_ms)
- The pointer to return the event to. The event is returned through this pointer. In the case of a timeout, a NULL value is returned.
- An integer value that defines the timeout: positive: Return when event is available or after timeout_ms milliseconds, whichever occurs first.0: Return immediately.negative: Block until an event is available.
The bps_get_event() function retrieves the next event for the application. The event is pulled from the active channel's event queue. If an event is available, it is immediately returned. If an event is not immediately available, the behavior of this function depends on the value of the timeout_ms parameter.
Note: Event "ownership" is not transferred to the application. An application must not call the bps_event_destroy() function on event pointers that are retrieved using the bps_get_event() function. The pointer to the event is valid until the bps_get_event() function is called again. Use the bps_channel_push_event() function to transfer ownership of the event to a different channel.
When an application needs to pull an event from a different channel's event queue, it should call the bps_channel_set_active() function to the desired channel.
BPS_SUCCESS when the function completes successfully, BPS_FAILURE with the errno value set otherwise. In the case of a timeout or when polling occurs, a value of BPS_SUCCESS is returned, but the event is set to a NULL value.