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_collector_t	pn_collector_t
	An event collector. More...

Enumerations
enum	pn_event_type_t { PN_EVENT_NONE , PN_REACTOR_INIT , PN_REACTOR_QUIESCED , PN_REACTOR_FINAL , PN_TIMER_TASK , PN_CONNECTION_INIT , PN_CONNECTION_BOUND , PN_CONNECTION_UNBOUND , PN_CONNECTION_LOCAL_OPEN , PN_CONNECTION_REMOTE_OPEN , PN_CONNECTION_LOCAL_CLOSE , PN_CONNECTION_REMOTE_CLOSE , PN_CONNECTION_FINAL , PN_SESSION_INIT , PN_SESSION_LOCAL_OPEN , PN_SESSION_REMOTE_OPEN , PN_SESSION_LOCAL_CLOSE , PN_SESSION_REMOTE_CLOSE , PN_SESSION_FINAL , PN_LINK_INIT , PN_LINK_LOCAL_OPEN , PN_LINK_REMOTE_OPEN , PN_LINK_LOCAL_CLOSE , PN_LINK_REMOTE_CLOSE , PN_LINK_LOCAL_DETACH , PN_LINK_REMOTE_DETACH , PN_LINK_FLOW , PN_LINK_FINAL , PN_DELIVERY , PN_TRANSPORT , PN_TRANSPORT_AUTHENTICATED , PN_TRANSPORT_ERROR , PN_TRANSPORT_HEAD_CLOSED , PN_TRANSPORT_TAIL_CLOSED , PN_TRANSPORT_CLOSED , PN_SELECTABLE_INIT , PN_SELECTABLE_UPDATED , PN_SELECTABLE_READABLE , PN_SELECTABLE_WRITABLE , PN_SELECTABLE_ERROR , PN_SELECTABLE_EXPIRED , PN_SELECTABLE_FINAL , PN_CONNECTION_WAKE , PN_LISTENER_ACCEPT , PN_LISTENER_CLOSE , PN_PROACTOR_INTERRUPT , PN_PROACTOR_TIMEOUT , PN_PROACTOR_INACTIVE , PN_LISTENER_OPEN , PN_RAW_CONNECTION_CONNECTED , PN_RAW_CONNECTION_CLOSED_READ , PN_RAW_CONNECTION_CLOSED_WRITE , PN_RAW_CONNECTION_DISCONNECTED , PN_RAW_CONNECTION_NEED_READ_BUFFERS , PN_RAW_CONNECTION_NEED_WRITE_BUFFERS , PN_RAW_CONNECTION_READ , PN_RAW_CONNECTION_WRITTEN , PN_RAW_CONNECTION_WAKE , PN_RAW_CONNECTION_DRAIN_BUFFERS }
	An event type. 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...

void	pn_collector_drain (pn_collector_t *collector)
	Drain a collector: remove and discard all events. 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)
	Remove the head event on a collector. More...

pn_event_t *	pn_collector_next (pn_collector_t *collector)
	Pop and return the head event, returns NULL if the collector is empty. More...

pn_event_t *	pn_collector_prev (pn_collector_t *collector)
	Return the same pointer as the most recent call to pn_collector_next(). More...

bool	pn_collector_more (pn_collector_t *collector)
	Check if there are more events after the current head 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...

struct pn_condition_t *	pn_event_condition (pn_event_t *event)
	If the event context object has a condition and the condition is set return it, otherwise return NULL. More...

Detailed Description

Protocol and transport events.

Typedef Documentation

◆ pn_event_t

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:

Deliveries always have a single parent Link
Links always have a single parent Session
Sessions always have a single parent Connection
Connections optionally have at most one associated Transport
Transports optionally have at most one associated Connection

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.

◆ pn_collector_t

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.

Enumeration Type Documentation

◆ pn_event_type_t

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 to 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 to 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_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_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 has an incoming connection, call pn_listener_accept2() to accept it. 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 has become inactive: all listeners and connections were closed and the timeout (if set) expired or was cancelled. There will be no further events unless new listeners or connections are opened, or a new timeout is set (possibly in other threads in a multi-threaded program.) Events of this type point to the pn_proactor_t.
PN_LISTENER_OPEN	The listener is listening. Events of this type point to the pn_listener_t.
PN_RAW_CONNECTION_CONNECTED	The raw connection connected. Now would be a good time to give the raw connection some buffers to read bytes from the underlying socket. If you don't do it now you will get PN_RAW_CONNECTION_NEED_READ_BUFFERS (and PN_RAW_CONNECTION_NEED_WRITE_BUFFERS) events when the socket is readable (or writable) but there are not buffers available. Events of this type point to a pn_raw_connection_t
PN_RAW_CONNECTION_CLOSED_READ	The remote end of the raw connection closed the connection so that we can no longer read. When both this and PN_RAW_CONNECTION_CLOSED_WRITE event have occurred then the PN_RAW_CONNECTION_DISCONNECTED event will be generated. Events of this type point to a pn_raw_connection_t
PN_RAW_CONNECTION_CLOSED_WRITE	The remote end of the raw connection closed the connection so that we can no longer write. When both this and PN_RAW_CONNECTION_CLOSED_READ event have occurred then the PN_RAW_CONNECTION_DISCONNECTED event will be generated. Events of this type point to a pn_raw_connection_t
PN_RAW_CONNECTION_DISCONNECTED	The raw connection is disconnected. No more bytes will be read or written on the connection. Every buffer in use will already either have been returned using a PN_RAW_CONNECTION_READ or PN_RAW_CONNECTION_WRITTEN event. This event will always be the last for this raw connection, and so the application can clean up the raw connection at this point. Events of this type point to a pn_raw_connection_t
PN_RAW_CONNECTION_NEED_READ_BUFFERS	The raw connection might need more read buffers. The connection is readable, but the connection has no buffer to read the bytes into. If you supply some buffers now maybe you'll get a PN_RAW_CONNECTION_READ event soon, but no guarantees. This event is edge triggered and you will only get it once until you give the raw connection some more read buffers. Events of this type point to a pn_raw_connection_t
PN_RAW_CONNECTION_NEED_WRITE_BUFFERS	The raw connection might need more write buffers. The connection is writable but has no buffers to write. If you give the raw connection something to write using pn_raw_connection_write_buffers the raw connection can write them. It is not necessary to wait for this event before sending buffers to write, but it can be used to aid in flow control (maybe). This event is edge triggered and you will only get it once until you give the raw connection something more to write. Events of this type point to a pn_raw_connection_t
PN_RAW_CONNECTION_READ	The raw connection read bytes: The bytes that were read are in one of the read buffers given to the raw connection. This event will be sent if there are bytes that have been read in a buffer owned by the raw connection and there is no PN_RAW_CONNECTION_READ event still queued. When a connection closes all read buffers are returned to the application using PN_RAW_CONNECTION_READ events with empty buffers. Events of this type point to a pn_raw_connection_t
PN_RAW_CONNECTION_WRITTEN	The raw connection has finished a write and the buffers that were used are no longer in use and can be recycled. This event will be sent if there are buffers that have been written still owned by the raw connection and there is no PN_RAW_CONNECTION_WRITTEN event currently queued. When a connection closes all write buffers are returned using PN_RAW_CONNECTION_WRITTEN events. Events of this type point to a pn_raw_connection_t
PN_RAW_CONNECTION_WAKE	The raw connection was woken by pn_raw_connection_wake. Events of this type point to a pn_raw_connection_t
PN_RAW_CONNECTION_DRAIN_BUFFERS	The raw connection is returning all the remaining buffers to the application. The raw connection is about to disconnect and shutdown. To avoid leaking the buffers the application must take the buffers back used pn_raw_connection_take_read_buffers and pn_raw_connection_take_write_buffers. Events of this type point to a pn_raw_connection_t

Function Documentation

◆ pn_event_type_name()

const char* pn_event_type_name ( pn_event_type_t type )

Get a human readable name for an event type.

Parameters

[in] type an event type

Returns: a human readable name

Examples: broker.c, direct.c, receive.c, and send.c.

◆ pn_collector()

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.

◆ pn_collector_free()

void pn_collector_free ( pn_collector_t * collector )

Free a collector.

Parameters

[in] collector a collector to free, or NULL

◆ pn_collector_release()

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.

Parameters

[in] collector a collector object

◆ pn_collector_drain()

void pn_collector_drain ( pn_collector_t * collector )

Drain a collector: remove and discard all events.

Parameters

[in] collector a collector object

◆ pn_collector_put()

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.

Parameters

[in]	collector	a collector object
[in]	clazz	class of the context
[in]	context	the event context
[in]	type	the event type

Returns: a pointer to the newly created event or NULL if the event was elided

◆ pn_collector_peek()

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.

Parameters

[in] collector a collector object

Returns: a pointer to the head event contained in the collector

◆ pn_collector_pop()

bool pn_collector_pop ( pn_collector_t * collector )

Remove the head event on a collector.

Parameters

[in] collector a collector object

Returns: true if the event was popped, false if the collector is empty

◆ pn_collector_next()

pn_event_t* pn_collector_next ( pn_collector_t * collector )

Pop and return the head event, returns NULL if the collector is empty.

The returned pointer is valid till the next call of pn_collector_next().

Parameters

[in] collector a collector object

Returns: the next event.

◆ pn_collector_prev()

pn_event_t* pn_collector_prev ( pn_collector_t * collector )

Return the same pointer as the most recent call to pn_collector_next().

Parameters

[in] collector a collector object

Returns: a pointer to the event returned by previous call to pn_collector_next()

◆ pn_collector_more()

bool pn_collector_more ( pn_collector_t * collector )

Check if there are more events after the current head event.

If this returns true, then pn_collector_peek() will return an event even after pn_collector_pop() is called.

Parameters

[in] collector a collector object

Returns: true if the collector has more than the current event

◆ pn_event_type()

pn_event_type_t pn_event_type ( pn_event_t * event )

Get the type of an event.

Parameters

[in] event an event object

Returns: the type of the event

Examples: broker.c, direct.c, receive.c, and send.c.

◆ pn_event_class()

const pn_class_t* pn_event_class ( pn_event_t * event )

Get the class associated with the event context.

Parameters

[in] event an event object

Returns: the class associated with the event context

◆ pn_event_connection()

pn_connection_t* pn_event_connection ( pn_event_t * event )

Get the connection associated with an event.

Parameters

[in] event an event object

Returns: the connection associated with the event (or NULL)

Examples: broker.c, direct.c, receive.c, and send.c.

◆ pn_event_session()

pn_session_t* pn_event_session ( pn_event_t * event )

Get the session associated with an event.

Parameters

[in] event an event object

Returns: the session associated with the event (or NULL)

Examples: broker.c, direct.c, receive.c, and send.c.

◆ pn_event_link()

pn_link_t* pn_event_link ( pn_event_t * event )

Get the link associated with an event.

Parameters

[in] event an event object

Returns: the link associated with the event (or NULL)

Examples: broker.c, direct.c, receive.c, and send.c.

◆ pn_event_delivery()

pn_delivery_t* pn_event_delivery ( pn_event_t * event )

Get the delivery associated with an event.

Parameters

[in] event an event object

Returns: the delivery associated with the event (or NULL)

Examples: broker.c, direct.c, receive.c, and send.c.

◆ pn_event_transport()

pn_transport_t* pn_event_transport ( pn_event_t * event )

Get the transport associated with an event.

Parameters

[in] event an event object

Returns: the transport associated with the event (or NULL)

Examples: broker.c, direct.c, receive.c, and send.c.

◆ pn_event_attachments()

pn_record_t* pn_event_attachments ( pn_event_t * event )

Get any attachments associated with an event.

Parameters

[in] event an event object

Returns: the record holding the attachments

◆ pn_event_condition()

struct pn_condition_t* pn_event_condition ( pn_event_t * event )

If the event context object has a condition and the condition is set return it, otherwise return NULL.

If the event context object has remote and local conditions, try the remote condition first, then the local.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ pn_event_t

◆ pn_collector_t

Enumeration Type Documentation

◆ pn_event_type_t

Function Documentation

◆ pn_event_type_name()

◆ pn_collector()

◆ pn_collector_free()

◆ pn_collector_release()

◆ pn_collector_drain()

◆ pn_collector_put()

◆ pn_collector_peek()

◆ pn_collector_pop()

◆ pn_collector_next()

◆ pn_collector_prev()

◆ pn_collector_more()

◆ pn_event_type()

◆ pn_event_class()

◆ pn_event_connection()

◆ pn_event_session()

◆ pn_event_link()

◆ pn_event_delivery()

◆ pn_event_transport()

◆ pn_event_attachments()

◆ pn_event_condition()