awGetEvent

awGetEvent

BrokerError awGetEvent(
BrokerClient client,
int msecs,
BrokerEvent *event);

client	The Broker client whose next event is to be obtained.
msecs	Number of milliseconds to wait for an event before timing out. If set to AW_INFINITE, this function will wait indefinitely.
event	The event that is returned. This parameter is used for output.

Acknowledges all previously retrieved events for client, then obtains a single event for client, if available. If no events are currently available, this function will wait for the number of milliseconds specified by msecs. If the wait time expires, this function returns with error code AW_ERROR_TIMEOUT. Any event that is obtained may be one for which the client has registered a subscription, or it may be a delivered event.

Note:
Before exiting, Broker clients with an explicit-destroy life cycle that are using awGetEvent should explicitly acknowledge the receipt sequence number of the last event received using either awAcknowledge or awAcknowledgeThrough. Failure to do so will result in the last event being received again the next time you connect the Broker client.

Using this function on a client that has registered callback functions will temporarily disable the callback mechanism for this Broker client until this function returns.

The caller is responsible for calling awDeleteEvent for the output event.

Note:
The Broker will delete all guaranteed events from the event queue once they are acknowledged. If you wish to receive an event without acknowledging any previously retrieved events, use the awGetEventsWithAck function and specify a sequence number of -1.

Possible BrokerError major codes	Meaning
AW_ERROR_INTERRUPTED	The awInterruptGetEvents function was invoked.
AW_ERROR_INVALID_CLIENT	The client has been destroyed or disconnected.
AW_ERROR_NULL_PARAM	The parameter events is NULL.
AW_ERROR_OUT_OF_RANGE	The msecs parameter is less than -1.
AW_ERROR_TIMEOUT	The msecs time-out interval expired before an event arrived.