proton  0
Typedefs | Enumerations | Functions
Event

Typedefs

typedef struct pn_event_t pn_event_t
 An event provides notification of a state change within the protocol engine's object model. More...
 
typedef struct pn_collector_t pn_collector_t
 An event collector. More...
 

Enumerations

enum  pn_event_type_t {
  PN_EVENT_NONE = 0, 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
}
 An event type. More...
 

Functions

PN_EXTERN const char * pn_event_type_name (pn_event_type_t type)
 Get a human readable name for an event type. More...
 
PN_EXTERN pn_collector_tpn_collector (void)
 Construct a collector. More...
 
PN_EXTERN void pn_collector_free (pn_collector_t *collector)
 Free a collector. More...
 
PN_EXTERN void pn_collector_release (pn_collector_t *collector)
 Release a collector. More...
 
PN_EXTERN pn_event_tpn_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_EXTERN pn_event_tpn_collector_peek (pn_collector_t *collector)
 Access the head event contained by a collector. More...
 
PN_EXTERN bool pn_collector_pop (pn_collector_t *collector)
 Clear the head event on a collector. More...
 
PN_EXTERN bool pn_collector_more (pn_collector_t *collector)
 Check if there are more events after the current event. More...
 
PN_EXTERN pn_event_type_t pn_event_type (pn_event_t *event)
 Get the type of an event. More...
 
PN_EXTERN const pn_class_tpn_event_class (pn_event_t *event)
 Get the class associated with the event context. More...
 
PN_EXTERN void * pn_event_context (pn_event_t *event)
 Get the context associated with an event. More...
 
PN_EXTERN pn_handler_tpn_event_root (pn_event_t *event)
 Get the root handler the current event was dispatched to. More...
 
PN_EXTERN pn_connection_tpn_event_connection (pn_event_t *event)
 Get the connection associated with an event. More...
 
PN_EXTERN pn_session_tpn_event_session (pn_event_t *event)
 Get the session associated with an event. More...
 
PN_EXTERN pn_link_tpn_event_link (pn_event_t *event)
 Get the link associated with an event. More...
 
PN_EXTERN pn_delivery_tpn_event_delivery (pn_event_t *event)
 Get the delivery associated with an event. More...
 
PN_EXTERN pn_transport_tpn_event_transport (pn_event_t *event)
 Get the transport associated with an event. More...
 
PN_EXTERN pn_record_tpn_event_attachments (pn_event_t *event)
 Get any attachments associated with an event. More...
 

Detailed Description

Typedef Documentation

§ 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.

§ pn_event_t

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

§ 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 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_SELECTABLE_INIT 
PN_SELECTABLE_UPDATED 
PN_SELECTABLE_READABLE 
PN_SELECTABLE_WRITABLE 
PN_SELECTABLE_ERROR 
PN_SELECTABLE_EXPIRED 
PN_SELECTABLE_FINAL 

Function Documentation

§ pn_collector()

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_collector_free()

PN_EXTERN void pn_collector_free ( pn_collector_t collector)

Free a collector.

Parameters
[in]collectora collector to free, or NULL

§ pn_collector_more()

PN_EXTERN 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.

Parameters
[in]collectora collector object
Returns
true if the collector has more than the current event

§ pn_collector_peek()

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_collector_pop()

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_collector_put()

PN_EXTERN 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]collectora collector object
[in]clazzclass of the context
[in]contextthe event context
[in]typethe event type
Returns
a pointer to the newly created event or NULL if the event was elided

§ pn_collector_release()

PN_EXTERN 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]collectora collector object

§ pn_event_attachments()

PN_EXTERN pn_record_t* pn_event_attachments ( pn_event_t event)

Get any attachments associated with an event.

Parameters
[in]eventan event object
Returns
the record holding the attachments

§ pn_event_class()

PN_EXTERN const pn_class_t* pn_event_class ( pn_event_t event)

Get the class associated with the event context.

Parameters
[in]eventan event object
Returns
the class associated with the event context

§ pn_event_connection()

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_event_context()

PN_EXTERN void* pn_event_context ( pn_event_t event)

Get the context associated with an event.

§ pn_event_delivery()

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_event_link()

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_event_root()

PN_EXTERN pn_handler_t* pn_event_root ( pn_event_t event)

Get the root handler the current event was dispatched to.

§ pn_event_session()

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_event_transport()

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_event_type()

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_event_type_name()

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