awGetEvents

BrokerError awGetEvents(
BrokerClient client,
int max_events,
int msecs,
int *n,
BrokerEvent **events);

client	The Broker client requesting the event.
max_events	The maximum number of events to be returned.
msecs	The number of milliseconds to wait for the events before timing out. If set to AW_INFINITE, this function will wait indefinitely.
n	The number of events returned. This parameter is used for output.
events	An array of events. This parameter is used for output.

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

If the wait time expires, this function returns a BrokerError with a major code of AW_ERROR_TIMEOUT and n set to zero.

Note:
Before exiting, Broker clients with an explicit-destroy life cycle that are using awGetEvents 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 that client until this function returns.

The caller is responsible for calling awDeleteEvent on each event and then calling free on the array itself.

Note:
The Broker will delete all guaranteed events from the event queue once they are acknowledged. If you wish to receive multiple events 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 n or events is NULL.
AW_ERROR_OUT_OF_RANGE	The msecs parameter is less than -1 or max_events is less than zero.
AW_ERROR_TIMEOUT	The msecs time-out interval expired before any events arrived.