C AMQP Protocol Engine API  0.7
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Event
Collaboration diagram for Event:

Typedefs

typedef struct pn_event_t pn_event_t
 
typedef struct pn_collector_t pn_collector_t
 

Enumerations

enum  pn_event_category_t { PN_EVENT_CATEGORY_NONE = 0, PN_EVENT_CATEGORY_PROTOCOL = 0x00010000, PN_EVENT_CATEGORY_COUNT = 2 }
 
enum  pn_event_type_t {
  PN_EVENT_NONE = 0, PN_CONNECTION_REMOTE_STATE = PN_EVENT_CATEGORY_PROTOCOL+1, PN_CONNECTION_LOCAL_STATE = PN_EVENT_CATEGORY_PROTOCOL+2, PN_SESSION_REMOTE_STATE = PN_EVENT_CATEGORY_PROTOCOL+3,
  PN_SESSION_LOCAL_STATE = PN_EVENT_CATEGORY_PROTOCOL+4, PN_LINK_REMOTE_STATE = PN_EVENT_CATEGORY_PROTOCOL+5, PN_LINK_LOCAL_STATE = PN_EVENT_CATEGORY_PROTOCOL+6, PN_LINK_FLOW = PN_EVENT_CATEGORY_PROTOCOL+7,
  PN_DELIVERY = PN_EVENT_CATEGORY_PROTOCOL+8, PN_TRANSPORT = PN_EVENT_CATEGORY_PROTOCOL+9
}
 

Functions

PN_EXTERN const char * pn_event_type_name (pn_event_type_t type)
 
PN_EXTERN pn_collector_tpn_collector (void)
 
PN_EXTERN void pn_collector_free (pn_collector_t *collector)
 
PN_EXTERN pn_event_tpn_collector_peek (pn_collector_t *collector)
 
PN_EXTERN bool pn_collector_pop (pn_collector_t *collector)
 
PN_EXTERN pn_event_type_t pn_event_type (pn_event_t *event)
 
PN_EXTERN pn_event_category_t pn_event_category (pn_event_t *event)
 
PN_EXTERN pn_connection_tpn_event_connection (pn_event_t *event)
 
PN_EXTERN pn_session_tpn_event_session (pn_event_t *event)
 
PN_EXTERN pn_link_tpn_event_link (pn_event_t *event)
 
PN_EXTERN pn_delivery_tpn_event_delivery (pn_event_t *event)
 
PN_EXTERN pn_transport_tpn_event_transport (pn_event_t *event)
 

Detailed Description

Typedef Documentation

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_t pn_event_t

An event provides notification of a state change within the protocol engine's object model.

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.

Enumeration Type Documentation

Related events are grouped into categories

Enumerator
PN_EVENT_CATEGORY_NONE 
PN_EVENT_CATEGORY_PROTOCOL 
PN_EVENT_CATEGORY_COUNT 

An event type.

Enumerator
PN_EVENT_NONE 

Defined as a programming convenience. No event of this type will ever be generated.

PN_CONNECTION_REMOTE_STATE 

The endpoint state flags for a connection have changed. Events of this type point to the relevant connection as well as its associated transport.

PN_CONNECTION_LOCAL_STATE 
PN_SESSION_REMOTE_STATE 

The endpoint state flags for a session have changed. Events of this type point to the relevant session as well as its associated connection and transport.

PN_SESSION_LOCAL_STATE 
PN_LINK_REMOTE_STATE 

The endpoint state flags for a link have changed. Events of this type point to the relevant link as well as its associated session, connection, and transport.

PN_LINK_LOCAL_STATE 
PN_LINK_FLOW 

The flow control state for a link has changed. Events of this type point to the relevant link along with its associated session, connection, and transport.

PN_DELIVERY 

A delivery has been created or updated. Events of this type point to the relevant delivery as well as its associated link, session, connection, and transport.

PN_TRANSPORT 

The transport has new data to read and/or write. Events of this type point to the relevant transport as well as its associated connection.

Function Documentation

PN_EXTERN 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_EXTERN void pn_collector_free ( pn_collector_t collector)

Free a collector.

Parameters
[in]collectora collector to free, or NULL
PN_EXTERN 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]collectora collector object
Returns
a pointer to the head event contained in the collector
PN_EXTERN bool pn_collector_pop ( pn_collector_t collector)

Clear the head event on a collector.

Parameters
[in]collectora collector object
Returns
true if the event was popped, false if the collector is empty
PN_EXTERN pn_event_category_t pn_event_category ( pn_event_t event)

Get the category an event belongs to.

Parameters
[in]eventan event object
Returns
the category the event belongs to
PN_EXTERN pn_connection_t* pn_event_connection ( pn_event_t event)

Get the connection associated with an event.

Parameters
[in]eventan event object
Returns
the connection associated with the event (or NULL)
PN_EXTERN pn_delivery_t* pn_event_delivery ( pn_event_t event)

Get the delivery associated with an event.

Parameters
[in]eventan event object
Returns
the delivery associated with the event (or NULL)
PN_EXTERN pn_link_t* pn_event_link ( pn_event_t event)

Get the link associated with an event.

Parameters
[in]eventan event object
Returns
the link associated with the event (or NULL)
PN_EXTERN pn_session_t* pn_event_session ( pn_event_t event)

Get the session associated with an event.

Parameters
[in]eventan event object
Returns
the session associated with the event (or NULL)
PN_EXTERN pn_transport_t* pn_event_transport ( pn_event_t event)

Get the transport associated with an event.

Parameters
[in]eventan event object
Returns
the transport associated with the event (or NULL)
PN_EXTERN pn_event_type_t pn_event_type ( pn_event_t event)

Get the type of an event.

Parameters
[in]eventan event object
Returns
the type of the event
PN_EXTERN const char* pn_event_type_name ( pn_event_type_t  type)

Get a human readable name for an event type.

Parameters
[in]typean event type
Returns
a human readable name