Qpid Proton C API
0.16.0
|
Protocol and transport events. More...
Typedefs | |
typedef struct pn_event_t | pn_event_t |
Notification of a state change in the protocol engine. More... | |
typedef struct pn_event_batch_t | pn_event_batch_t |
Experimental - A batch of events to handle. More... | |
typedef struct pn_collector_t | pn_collector_t |
An event collector. More... | |
Functions | |
const char * | pn_event_type_name (pn_event_type_t type) |
Get a human readable name for an event type. More... | |
pn_collector_t * | pn_collector (void) |
Construct a collector. More... | |
void | pn_collector_free (pn_collector_t *collector) |
Free a collector. More... | |
void | pn_collector_release (pn_collector_t *collector) |
Release a collector. More... | |
pn_event_t * | pn_collector_put (pn_collector_t *collector, const pn_class_t *clazz, void *context, pn_event_type_t type) |
Place a new event on a collector. More... | |
pn_event_t * | pn_collector_peek (pn_collector_t *collector) |
Access the head event contained by a collector. More... | |
bool | pn_collector_pop (pn_collector_t *collector) |
Clear the head event on a collector. More... | |
pn_event_t * | pn_collector_next (pn_collector_t *collector) |
Return the next event to be handled. More... | |
pn_event_t * | pn_collector_prev (pn_collector_t *collector) |
Return the same event as the previous call to pn_collector_next() More... | |
bool | pn_collector_more (pn_collector_t *collector) |
Check if there are more events after the current event. More... | |
pn_event_type_t | pn_event_type (pn_event_t *event) |
Get the type of an event. More... | |
const pn_class_t * | pn_event_class (pn_event_t *event) |
Get the class associated with the event context. More... | |
void * | pn_event_context (pn_event_t *event) |
Get the context associated with an event. | |
pn_connection_t * | pn_event_connection (pn_event_t *event) |
Get the connection associated with an event. More... | |
pn_session_t * | pn_event_session (pn_event_t *event) |
Get the session associated with an event. More... | |
pn_link_t * | pn_event_link (pn_event_t *event) |
Get the link associated with an event. More... | |
pn_delivery_t * | pn_event_delivery (pn_event_t *event) |
Get the delivery associated with an event. More... | |
pn_transport_t * | pn_event_transport (pn_event_t *event) |
Get the transport associated with an event. More... | |
pn_record_t * | pn_event_attachments (pn_event_t *event) |
Get any attachments associated with an event. More... | |
pn_event_t * | pn_event_batch_next (pn_event_batch_t *batch) |
Experimental - Remove the next event from the batch and return it. More... | |
Protocol and transport events.
typedef struct pn_collector_t pn_collector_t |
An event collector.
A pn_collector_t may be used to register interest in being notified of high level events that can occur to the various objects representing AMQP endpoint state. See pn_event_t for more details.
typedef struct pn_event_batch_t pn_event_batch_t |
Experimental - A batch of events to handle.
Call pn_event_batch_next() in a loop until it returns NULL to handle them.
typedef struct pn_event_t pn_event_t |
Notification of a state change in the protocol engine.
The AMQP endpoint state modeled by the protocol engine is captured by the following object types: Deliveries , Links , Sessions , Connections , and Transports . These objects are related as follows:
Every event has a type (see pn_event_type_t) that identifies what sort of state change has occurred along with a pointer to the object whose state has changed (as well as its associated objects).
Events are accessed by creating a Collector with pn_collector() and registering it with the Connection of interest through use of pn_connection_collect(). Once a collector has been registered, pn_collector_peek() and pn_collector_pop() are used to access and process events.
enum pn_event_type_t |
An event type.
Enumerator | |
---|---|
PN_EVENT_NONE |
Defined as a programming convenience. No event of this type will ever be generated. |
PN_REACTOR_INIT |
A reactor has been started. Events of this type point to the reactor. |
PN_REACTOR_QUIESCED |
A reactor has no more events to process. Events of this type point to the reactor. |
PN_REACTOR_FINAL |
A reactor has been stopped. Events of this type point to the reactor. |
PN_TIMER_TASK |
A timer event has occurred. |
PN_CONNECTION_INIT |
The connection has been created. This is the first event that will ever be issued for a connection. Events of this type point to the relevant connection. |
PN_CONNECTION_BOUND |
The connection has been bound to a transport. This event is issued when the pn_transport_bind() operation is invoked. |
PN_CONNECTION_UNBOUND |
The connection has been unbound from its transport. This event is issued when the pn_transport_unbind() operation is invoked. |
PN_CONNECTION_LOCAL_OPEN |
The local connection endpoint has been closed. Events of this type point to the relevant connection. |
PN_CONNECTION_REMOTE_OPEN |
The remote endpoint has opened the connection. Events of this type point to the relevant connection. |
PN_CONNECTION_LOCAL_CLOSE |
The local connection endpoint has been closed. Events of this type point to the relevant connection. |
PN_CONNECTION_REMOTE_CLOSE |
The remote endpoint has closed the connection. Events of this type point to the relevant connection. |
PN_CONNECTION_FINAL |
The connection has been freed and any outstanding processing has been completed. This is the final event that will ever be issued for a connection. |
PN_SESSION_INIT |
The session has been created. This is the first event that will ever be issued for a session. |
PN_SESSION_LOCAL_OPEN |
The local session endpoint has been opened. Events of this type point ot the relevant session. |
PN_SESSION_REMOTE_OPEN |
The remote endpoint has opened the session. Events of this type point to the relevant session. |
PN_SESSION_LOCAL_CLOSE |
The local session endpoint has been closed. Events of this type point ot the relevant session. |
PN_SESSION_REMOTE_CLOSE |
The remote endpoint has closed the session. Events of this type point to the relevant session. |
PN_SESSION_FINAL |
The session has been freed and any outstanding processing has been completed. This is the final event that will ever be issued for a session. |
PN_LINK_INIT |
The link has been created. This is the first event that will ever be issued for a link. |
PN_LINK_LOCAL_OPEN |
The local link endpoint has been opened. Events of this type point ot the relevant link. |
PN_LINK_REMOTE_OPEN |
The remote endpoint has opened the link. Events of this type point to the relevant link. |
PN_LINK_LOCAL_CLOSE |
The local link endpoint has been closed. Events of this type point ot the relevant link. |
PN_LINK_REMOTE_CLOSE |
The remote endpoint has closed the link. Events of this type point to the relevant link. |
PN_LINK_LOCAL_DETACH |
The local link endpoint has been detached. Events of this type point to the relevant link. |
PN_LINK_REMOTE_DETACH |
The remote endpoint has detached the link. Events of this type point to the relevant link. |
PN_LINK_FLOW |
The flow control state for a link has changed. Events of this type point to the relevant link. |
PN_LINK_FINAL |
The link has been freed and any outstanding processing has been completed. This is the final event that will ever be issued for a link. Events of this type point to the relevant link. |
PN_DELIVERY |
A delivery has been created or updated. Events of this type point to the relevant delivery. |
PN_TRANSPORT |
The transport has new data to read and/or write. Events of this type point to the relevant transport. |
PN_TRANSPORT_AUTHENTICATED |
The transport has authenticated, if this is received by a server the associated transport has authenticated an incoming connection and pn_transport_get_user() can be used to obtain the authenticated user. |
PN_TRANSPORT_ERROR |
Indicates that a transport error has occurred. Use pn_transport_condition() to access the details of the error from the associated transport. |
PN_TRANSPORT_HEAD_CLOSED |
Indicates that the "head" or writing end of the transport has been closed. This means the transport will never produce more bytes for output to the network. Events of this type point to the relevant transport. |
PN_TRANSPORT_WRITE_CLOSED |
The write side of the transport is closed, it will no longer produce bytes to write to external IO. Synonynm for PN_TRANSPORT_HEAD_CLOSED |
PN_TRANSPORT_TAIL_CLOSED |
Indicates that the tail of the transport has been closed. This means the transport will never be able to process more bytes from the network. Events of this type point to the relevant transport. |
PN_TRANSPORT_READ_CLOSED |
The read side of the transport is closed, it will no longer read bytes from external IO. Synonynm for PN_TRANSPORT_TAIL_CLOSED |
PN_TRANSPORT_CLOSED |
Indicates that the both the head and tail of the transport are closed. Events of this type point to the relevant transport. |
PN_CONNECTION_WAKE |
pn_connection_wake() was called. Events of this type point to the pn_connection_t. |
PN_LISTENER_ACCEPT |
Indicates the listener is ready to call pn_listener_accept() Events of this type point to the pn_listener_t. |
PN_LISTENER_CLOSE |
Indicates the listener has closed. pn_listener_condition() provides error information. Events of this type point to the pn_listener_t. |
PN_PROACTOR_INTERRUPT |
Indicates pn_proactor_interrupt() was called to interrupt a proactor thread Events of this type point to the pn_proactor_t. |
PN_PROACTOR_TIMEOUT |
Timeout set by pn_proactor_set_timeout() time limit expired. Events of this type point to the pn_proactor_t. |
PN_PROACTOR_INACTIVE |
The proactor becaome inactive: all listeners and connections are closed and their events processed, the timeout is expired. Events of this type point to the pn_proactor_t. |
pn_collector_t* pn_collector | ( | void | ) |
Construct a collector.
A collector is used to register interest in events produced by one or more pn_connection_t objects. Collectors are not currently thread safe, so synchronization must be used if they are to be shared between multiple connection objects.
void pn_collector_free | ( | pn_collector_t * | collector | ) |
Free a collector.
[in] | collector | a collector to free, or NULL |
bool pn_collector_more | ( | pn_collector_t * | collector | ) |
Check if there are more events after the current event.
If this returns true, then pn_collector_peek() will return an event even after pn_collector_pop() is called.
[in] | collector | a collector object |
pn_event_t* pn_collector_next | ( | pn_collector_t * | collector | ) |
Return the next event to be handled.
Returns the head event if it has not previously been returned by pn_collector_next(), otherwise does pn_collector_pop() and returns the new head event.
The returned pointer is valid till the next call of pn_collector_pop(), pn_collector_next(), pn_collector_release() or pn_collector_free()
[in] | collector | a collector object |
pn_event_t* pn_collector_peek | ( | pn_collector_t * | collector | ) |
Access the head event contained by a collector.
This operation will continue to return the same event until it is cleared by using pn_collector_pop. The pointer return by this operation will be valid until pn_collector_pop is invoked or pn_collector_free is called, whichever happens sooner.
[in] | collector | a collector object |
bool pn_collector_pop | ( | pn_collector_t * | collector | ) |
Clear the head event on a collector.
[in] | collector | a collector object |
pn_event_t* pn_collector_prev | ( | pn_collector_t * | collector | ) |
Return the same event as the previous call to pn_collector_next()
The returned pointer is valid till the next call of pn_collector_pop(), pn_collector_next(), pn_collector_release() or pn_collector_free()
[in] | collector | a collector object |
pn_event_t* pn_collector_put | ( | pn_collector_t * | collector, |
const pn_class_t * | clazz, | ||
void * | context, | ||
pn_event_type_t | type | ||
) |
Place a new event on a collector.
This operation will create a new event of the given type and context and return a pointer to the newly created event. In some cases an event of the given type and context can be elided. When this happens, this operation will return a NULL pointer.
[in] | collector | a collector object |
[in] | clazz | class of the context |
[in] | context | the event context |
[in] | type | the event type |
void pn_collector_release | ( | pn_collector_t * | collector | ) |
Release a collector.
Once in a released state a collector will drain any internally queued events (thereby releasing any pointers they may hold), shrink it's memory footprint to a minimum, and discard any newly created events.
[in] | collector | a collector object |
pn_record_t* pn_event_attachments | ( | pn_event_t * | event | ) |
Get any attachments associated with an event.
[in] | event | an event object |
pn_event_t* pn_event_batch_next | ( | pn_event_batch_t * | batch | ) |
Experimental - Remove the next event from the batch and return it.
NULL means the batch is empty. The returned event pointer is valid until pn_event_batch_next() is called again on the same batch.
const pn_class_t* pn_event_class | ( | pn_event_t * | event | ) |
Get the class associated with the event context.
[in] | event | an event object |
pn_connection_t* pn_event_connection | ( | pn_event_t * | event | ) |
pn_delivery_t* pn_event_delivery | ( | pn_event_t * | event | ) |
pn_link_t* pn_event_link | ( | pn_event_t * | event | ) |
pn_session_t* pn_event_session | ( | pn_event_t * | event | ) |
pn_transport_t* pn_event_transport | ( | pn_event_t * | event | ) |
pn_event_type_t pn_event_type | ( | pn_event_t * | event | ) |
const char* pn_event_type_name | ( | pn_event_type_t | type | ) |