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

Modules

 Condition
 

Macros

#define PN_LOCAL_UNINIT   (1)
 
#define PN_LOCAL_ACTIVE   (2)
 
#define PN_LOCAL_CLOSED   (4)
 
#define PN_REMOTE_UNINIT   (8)
 
#define PN_REMOTE_ACTIVE   (16)
 
#define PN_REMOTE_CLOSED   (32)
 
#define PN_LOCAL_MASK   (PN_LOCAL_UNINIT | PN_LOCAL_ACTIVE | PN_LOCAL_CLOSED)
 
#define PN_REMOTE_MASK   (PN_REMOTE_UNINIT | PN_REMOTE_ACTIVE | PN_REMOTE_CLOSED)
 

Typedefs

typedef int pn_state_t
 
typedef struct pn_connection_t pn_connection_t
 

Functions

PN_EXTERN pn_connection_tpn_connection (void)
 
PN_EXTERN void pn_connection_free (pn_connection_t *connection)
 
PN_EXTERN pn_error_tpn_connection_error (pn_connection_t *connection)
 
PN_EXTERN void pn_connection_collect (pn_connection_t *connection, pn_collector_t *collector)
 
PN_EXTERN void * pn_connection_get_context (pn_connection_t *connection)
 
PN_EXTERN void pn_connection_set_context (pn_connection_t *connection, void *context)
 
PN_EXTERN pn_state_t pn_connection_state (pn_connection_t *connection)
 
PN_EXTERN void pn_connection_open (pn_connection_t *connection)
 
PN_EXTERN void pn_connection_close (pn_connection_t *connection)
 
PN_EXTERN void pn_connection_reset (pn_connection_t *connection)
 
PN_EXTERN pn_condition_tpn_connection_condition (pn_connection_t *connection)
 
PN_EXTERN pn_condition_tpn_connection_remote_condition (pn_connection_t *connection)
 
PN_EXTERN const char * pn_connection_get_container (pn_connection_t *connection)
 
PN_EXTERN void pn_connection_set_container (pn_connection_t *connection, const char *container)
 
PN_EXTERN const char * pn_connection_get_hostname (pn_connection_t *connection)
 
PN_EXTERN void pn_connection_set_hostname (pn_connection_t *connection, const char *hostname)
 
PN_EXTERN const char * pn_connection_remote_container (pn_connection_t *connection)
 
PN_EXTERN const char * pn_connection_remote_hostname (pn_connection_t *connection)
 
PN_EXTERN pn_data_tpn_connection_offered_capabilities (pn_connection_t *connection)
 
PN_EXTERN pn_data_tpn_connection_desired_capabilities (pn_connection_t *connection)
 
PN_EXTERN pn_data_tpn_connection_properties (pn_connection_t *connection)
 
PN_EXTERN pn_data_tpn_connection_remote_offered_capabilities (pn_connection_t *connection)
 
PN_EXTERN pn_data_tpn_connection_remote_desired_capabilities (pn_connection_t *connection)
 
PN_EXTERN pn_data_tpn_connection_remote_properties (pn_connection_t *connection)
 
PN_EXTERN pn_transport_tpn_connection_transport (pn_connection_t *connection)
 

Detailed Description

Macro Definition Documentation

#define PN_LOCAL_ACTIVE   (2)

The local endpoint state is active.

#define PN_LOCAL_CLOSED   (4)

The local endpoint state is closed.

#define PN_LOCAL_MASK   (PN_LOCAL_UNINIT | PN_LOCAL_ACTIVE | PN_LOCAL_CLOSED)

A mask for values of pn_state_t that preserves only the local bits of an endpoint's state.

#define PN_LOCAL_UNINIT   (1)

The local endpoint state is uninitialized.

#define PN_REMOTE_ACTIVE   (16)

The remote endpoint state is active.

#define PN_REMOTE_CLOSED   (32)

The remote endpoint state is closed.

#define PN_REMOTE_MASK   (PN_REMOTE_UNINIT | PN_REMOTE_ACTIVE | PN_REMOTE_CLOSED)

A mask for values of pn_state_t that preserves only the remote bits of an endpoint's state.

#define PN_REMOTE_UNINIT   (8)

The remote endpoint state is uninitialized.

Typedef Documentation

An AMQP Connection object.

A pn_connection_t object encapsulates all of the endpoint state associated with an AMQP Connection. A pn_connection_t object contains zero or more pn_session_t objects, which in turn contain zero or more pn_link_t objects. Each pn_link_t object contains an ordered sequence of pn_delivery_t objects. A link is either a Sender , or a Receiver , but never both.

typedef int pn_state_t

Holds the state flags for an AMQP endpoint.

A pn_state_t is an integral value with flags that encode both the local and remote state of an AMQP Endpoint (Connection , Session , or Link ). The local portion of the state may be accessed using PN_LOCAL_MASK, and the remote portion may be accessed using PN_REMOTE_MASK. Individual bits may be accessed using PN_LOCAL_UNINIT, PN_LOCAL_ACTIVE, PN_LOCAL_CLOSED, and PN_REMOTE_UNINIT, PN_REMOTE_ACTIVE, PN_REMOTE_CLOSED.

Every AMQP endpoint (Connection , Session , or Link ) starts out in an uninitialized state and then proceeds linearly to an active and then closed state. This lifecycle occurs at both endpoints involved, and so the state model for an endpoint includes not only the known local state, but also the last known state of the remote endpoint.

Function Documentation

PN_EXTERN pn_connection_t* pn_connection ( void  )

Factory to construct a new Connection.

Returns
pointer to a new connection object.
PN_EXTERN void pn_connection_close ( pn_connection_t connection)

Close a connection.

Once this operation has completed, the PN_LOCAL_CLOSED state flag will be set. This may be called without calling pn_connection_open, in this case it is equivalent to calling pn_connection_open followed by pn_connection_close.

Parameters
[in]connectiona connection object
PN_EXTERN void pn_connection_collect ( pn_connection_t connection,
pn_collector_t collector 
)

Associate a connection object with an event collector.

By associating a connection object with an event collector, key changes in endpoint state are reported to the collector via pn_event_t objects that can be inspected and processed. See pn_event_t for more details on the kinds of events.

Note that by registering a collector, the user is requesting that an indefinite number of events be queued up on his behalf. This means that unless the application eventually processes these events, the storage requirements for keeping them will grow without bound. In other words, don't register a collector with a connection if you never intend to process any of the events.

Parameters
[in]connectionthe connection object
[in]collectorthe event collector
PN_EXTERN pn_condition_t* pn_connection_condition ( pn_connection_t connection)

Get the local condition associated with the connection endpoint.

The pn_condition_t object retrieved may be modified prior to closing the connection in order to indicate a particular condition exists when the connection closes. This is normally used to communicate error conditions to the remote peer, however it may also be used in non error cases such as redirects. See pn_condition_t for more details.

The pointer returned by this operation is valid until the connection object is freed.

Parameters
[in]connectionthe connection object
Returns
the connection's local condition object
PN_EXTERN pn_data_t* pn_connection_desired_capabilities ( pn_connection_t connection)

Access/modify the AMQP desired capabilities data for a connection object.

This operation will return a pointer to a pn_data_t object that is valid until the connection object is freed. Any data contained by the pn_data_t object will be sent as the desired capabilites for the parent connection object. Note that this MUST take the form of an array of symbols to be valid.

The pn_data_t pointer returned is valid until the connection object is freed.

Parameters
[in]connectionthe connection object
Returns
a pointer to a pn_data_t representing the desired capabilities
PN_EXTERN pn_error_t* pn_connection_error ( pn_connection_t connection)

Get additional error information associated with the connection.

Whenever a connection operation fails (i.e. returns an error code), additional error details can be obtained using this function. The error object that is returned may also be used to clear the error condition.

The pointer returned by this operation is valid until the connection object is freed.

Parameters
[in]connectionthe connection object
Returns
the connection's error object
PN_EXTERN void pn_connection_free ( pn_connection_t connection)

Free a connection object.

When a connection object is freed, all pn_session_t, pn_link_t, and pn_delivery_t objects associated with the connection are also freed.

Parameters
[in]connectionthe connection object to free (or NULL)
PN_EXTERN const char* pn_connection_get_container ( pn_connection_t connection)

Get the AMQP Container name advertised by a connection object.

The pointer returned by this operation is valid until pn_connection_set_container is called, or until the connection object is freed, whichever happens sooner.

Parameters
[in]connectionthe connection object
Returns
a pointer to the container name
PN_EXTERN void* pn_connection_get_context ( pn_connection_t connection)

Get the application context that is associated with a connection object.

The application context for a connection may be set using pn_connection_set_context.

Parameters
[in]connectionthe connection whose context is to be returned.
Returns
the application context for the connection object
PN_EXTERN const char* pn_connection_get_hostname ( pn_connection_t connection)

Get the value of the AMQP Hostname used by a connection object.

The pointer returned by this operation is valid until pn_connection_set_hostname is called, or until the connection object is freed, whichever happens sooner.

Parameters
[in]connectionthe connection object
Returns
a pointer to the hostname
PN_EXTERN pn_data_t* pn_connection_offered_capabilities ( pn_connection_t connection)

Access/modify the AMQP offered capabilities data for a connection object.

This operation will return a pointer to a pn_data_t object that is valid until the connection object is freed. Any data contained by the pn_data_t object will be sent as the offered capabilites for the parent connection object. Note that this MUST take the form of an array of symbols to be valid.

The pn_data_t pointer returned is valid until the connection object is freed.

Parameters
[in]connectionthe connection object
Returns
a pointer to a pn_data_t representing the offered capabilities
PN_EXTERN void pn_connection_open ( pn_connection_t connection)

Open a connection.

Once this operation has completed, the PN_LOCAL_ACTIVE state flag will be set.

Parameters
[in]connectiona connection object
PN_EXTERN pn_data_t* pn_connection_properties ( pn_connection_t connection)

Access/modify the AMQP properties data for a connection object.

This operation will return a pointer to a pn_data_t object that is valid until the connection object is freed. Any data contained by the pn_data_t object will be sent as the AMQP properties for the parent connection object. Note that this MUST take the form of a symbol keyed map to be valid.

The pn_data_t pointer returned is valid until the connection object is freed.

Parameters
[in]connectionthe connection object
Returns
a pointer to a pn_data_t representing the connection properties
PN_EXTERN pn_condition_t* pn_connection_remote_condition ( pn_connection_t connection)

Get the remote condition associated with the connection endpoint.

The pn_condition_t object retrieved may be examined in order to determine whether the remote peer was indicating some sort of exceptional condition when the remote connection endpoint was closed. The pn_condition_t object returned may not be modified.

The pointer returned by this operation is valid until the connection object is freed.

Parameters
[in]connectionthe connection object
Returns
the connection's remote condition object
PN_EXTERN const char* pn_connection_remote_container ( pn_connection_t connection)

Get the AMQP Container name advertised by the remote connection endpoint.

This will return NULL until the PN_REMOTE_ACTIVE state is reached. See pn_state_t for more details on endpoint state.

Any non null pointer returned by this operation will be valid until the connection object is unbound from a transport or freed, whichever happens sooner.

Parameters
[in]connectionthe connection object
Returns
a pointer to the remote container name
PN_EXTERN pn_data_t* pn_connection_remote_desired_capabilities ( pn_connection_t connection)

Access the AMQP desired capabilites supplied by the remote connection endpoint.

This operation will return a pointer to a pn_data_t object that is valid until the connection object is freed. This data object will be empty until the remote connection is opened as indicated by the PN_REMOTE_ACTIVE flag.

Parameters
[in]connectionthe connection object
Returns
the remote desired capabilities
PN_EXTERN const char* pn_connection_remote_hostname ( pn_connection_t connection)

Get the AMQP Hostname set by the remote connection endpoint.

This will return NULL until the PN_REMOTE_ACTIVE state is reached. See pn_state_t for more details on endpoint state.

Any non null pointer returned by this operation will be valid until the connection object is unbound from a transport or freed, whichever happens sooner.

Parameters
[in]connectionthe connection object
Returns
a pointer to the remote hostname
PN_EXTERN pn_data_t* pn_connection_remote_offered_capabilities ( pn_connection_t connection)

Access the AMQP offered capabilites supplied by the remote connection endpoint.

This operation will return a pointer to a pn_data_t object that is valid until the connection object is freed. This data object will be empty until the remote connection is opened as indicated by the PN_REMOTE_ACTIVE flag.

Parameters
[in]connectionthe connection object
Returns
the remote offered capabilities
PN_EXTERN pn_data_t* pn_connection_remote_properties ( pn_connection_t connection)

Access the AMQP connection properties supplied by the remote connection endpoint.

This operation will return a pointer to a pn_data_t object that is valid until the connection object is freed. This data object will be empty until the remote connection is opened as indicated by the PN_REMOTE_ACTIVE flag.

Parameters
[in]connectionthe connection object
Returns
the remote connection properties
PN_EXTERN void pn_connection_reset ( pn_connection_t connection)

Reset a connection object back to the uninitialized state.

Note that this does not remove any contained pn_session_t, pn_link_t, and pn_delivery_t objects.

Parameters
[in]connectiona connection object
PN_EXTERN void pn_connection_set_container ( pn_connection_t connection,
const char *  container 
)

Set the AMQP Container name advertised by a connection object.

Parameters
[in]connectionthe connection object
[in]containerthe container name
PN_EXTERN void pn_connection_set_context ( pn_connection_t connection,
void *  context 
)

Set a new application context for a connection object.

The application context for a connection object may be retrieved using pn_connection_get_context.

Parameters
[in]connectionthe connection object
[in]contextthe application context
PN_EXTERN void pn_connection_set_hostname ( pn_connection_t connection,
const char *  hostname 
)

Set the value of the AMQP Hostname used by a connection object.

Parameters
[in]connectionthe connection object
[in]hostnamethe hostname
PN_EXTERN pn_state_t pn_connection_state ( pn_connection_t connection)

Get the endpoint state flags for a connection.

Parameters
[in]connectionthe connection
Returns
the connection's state flags
PN_EXTERN pn_transport_t* pn_connection_transport ( pn_connection_t connection)

Get the transport bound to a connection object.

If the connection is unbound, then this operation will return NULL.

Parameters
[in]connectionthe connection object
Returns
the transport bound to a connection, or NULL if the connection is unbound