A connection to a remote AMQP peer. More...

Macros
#define	PN_LOCAL_UNINIT
	The local endpoint state is uninitialized.

#define	PN_LOCAL_ACTIVE
	The local endpoint state is active.

#define	PN_LOCAL_CLOSED
	The local endpoint state is closed.

#define	PN_REMOTE_UNINIT
	The remote endpoint state is uninitialized.

#define	PN_REMOTE_ACTIVE
	The remote endpoint state is active.

#define	PN_REMOTE_CLOSED
	The remote endpoint state is closed.

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

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

Typedefs
typedef int	pn_state_t
	Holds the state flags for an AMQP endpoint.

typedef struct pn_connection_t	pn_connection_t
	An AMQP Connection object.

Functions
pn_connection_t *	pn_connection (void)
	Factory to construct a new Connection.

void	pn_connection_free (pn_connection_t *connection)
	Free a connection object.

void	pn_connection_release (pn_connection_t *connection)
	Release a connection object.

pn_error_t *	pn_connection_error (pn_connection_t *connection)
	Deprecated - Use pn_connection_condition().

void	pn_connection_collect (pn_connection_t connection, pn_collector_t collector)
	Associate a connection object with an event collector.

pn_collector_t *	pn_connection_collector (pn_connection_t *connection)
	Get the collector set with pn_connection_collect()

void *	pn_connection_get_context (pn_connection_t *connection)
	Get the application context that is associated with a connection object.

void	pn_connection_set_context (pn_connection_t connection, void context)
	Set a new application context for a connection object.

pn_record_t *	pn_connection_attachments (pn_connection_t *connection)
	Get the attachments that are associated with a connection object.

pn_state_t	pn_connection_state (pn_connection_t *connection)
	Get the endpoint state flags for a connection.

void	pn_connection_open (pn_connection_t *connection)
	Open a connection.

void	pn_connection_close (pn_connection_t *connection)
	Close a connection.

void	pn_connection_reset (pn_connection_t *connection)
	Reset a connection object back to the uninitialized state.

pn_condition_t *	pn_connection_condition (pn_connection_t *connection)
	Get the local condition associated with the connection endpoint.

pn_condition_t *	pn_connection_remote_condition (pn_connection_t *connection)
	Get the remote condition associated with the connection endpoint.

const char *	pn_connection_get_container (pn_connection_t *connection)
	Get the AMQP Container name advertised by a connection object.

void	pn_connection_set_container (pn_connection_t connection, const char container)
	Set the AMQP Container name advertised by a connection object.

void	pn_connection_set_user (pn_connection_t connection, const char user)
	Set the authentication username for a client connection.

void	pn_connection_set_password (pn_connection_t connection, const char password)
	Set the authentication password for a client connection.

void	pn_connection_set_authorization (pn_connection_t connection, const char authzid)
	Set the authorization id for a client connection.

const char *	pn_connection_get_user (pn_connection_t *connection)
	Get the authentication username for a client connection.

const char *	pn_connection_get_authorization (pn_connection_t *connection)
	Get the authorization id for a client connection.

const char *	pn_connection_get_hostname (pn_connection_t *connection)
	Get the value of the AMQP Hostname used by a connection object.

void	pn_connection_set_hostname (pn_connection_t connection, const char hostname)
	Set the name of the virtual host (either fully qualified or relative) to which this connection is connecting to.

const char *	pn_connection_remote_container (pn_connection_t *connection)
	Get the AMQP Container name advertised by the remote connection endpoint.

const char *	pn_connection_remote_hostname (pn_connection_t *connection)
	Get the AMQP Hostname set by the remote connection endpoint.

pn_data_t *	pn_connection_offered_capabilities (pn_connection_t *connection)
	Access/modify the AMQP offered capabilities data for a connection object.

pn_data_t *	pn_connection_desired_capabilities (pn_connection_t *connection)
	Access/modify the AMQP desired capabilities data for a connection object.

pn_data_t *	pn_connection_properties (pn_connection_t *connection)
	Access/modify the AMQP properties data for a connection object.

pn_data_t *	pn_connection_remote_offered_capabilities (pn_connection_t *connection)
	Access the AMQP offered capabilities supplied by the remote connection endpoint.

pn_data_t *	pn_connection_remote_desired_capabilities (pn_connection_t *connection)
	Access the AMQP desired capabilities supplied by the remote connection endpoint.

pn_data_t *	pn_connection_remote_properties (pn_connection_t *connection)
	Access the AMQP connection properties supplied by the remote connection endpoint.

pn_transport_t *	pn_connection_transport (pn_connection_t *connection)
	Get the transport bound to a connection object.

Detailed Description

A connection to a remote AMQP peer.

Typedef Documentation

◆ pn_state_t

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.

◆ pn_connection_t

typedef struct pn_connection_t pn_connection_t

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.

Function Documentation

◆ pn_connection()

pn_connection_t * pn_connection ( void )

Factory to construct a new Connection.

Returns: pointer to a new connection object.

◆ pn_connection_free()

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] connection the connection object to free (or NULL)

◆ pn_connection_release()

void pn_connection_release ( pn_connection_t * connection )

Release a connection object.

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

Parameters

[in] connection the connection object to be released

◆ pn_connection_error()

pn_error_t * pn_connection_error ( pn_connection_t * connection )

Deprecated - Use pn_connection_condition().

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.

Deprecation notice: note that this will always return an empty error object

Parameters

[in] connection the connection object

Returns: the connection's error object

◆ pn_connection_collect()

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]	connection	the connection object
[in]	collector	the event collector

◆ pn_connection_collector()

pn_collector_t * pn_connection_collector ( pn_connection_t * connection )

Get the collector set with pn_connection_collect()

Returns: NULL if pn_connection_collect() has not been called.

◆ pn_connection_get_context()

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] connection the connection whose context is to be returned.

Returns: the application context for the connection object

Examples: broker.c.

◆ pn_connection_set_context()

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]	connection	the connection object
[in]	context	the application context

Examples: broker.c.

◆ pn_connection_attachments()

pn_record_t * pn_connection_attachments ( pn_connection_t * connection )

Get the attachments that are associated with a connection object.

Parameters

[in] connection the connection whose attachments are to be returned.

Returns: the attachments for the connection object

◆ pn_connection_state()

pn_state_t pn_connection_state ( pn_connection_t * connection )

Get the endpoint state flags for a connection.

Parameters

[in] connection the connection

Returns: the connection's state flags

◆ pn_connection_open()

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] connection the connection object

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

◆ pn_connection_close()

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] connection the connection object

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

◆ pn_connection_reset()

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] connection the connection object

◆ pn_connection_condition()

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] connection the connection object

Returns: the connection's local condition object

◆ pn_connection_remote_condition()

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] connection the connection object

Returns: the connection's remote condition object

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

◆ pn_connection_get_container()

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] connection the connection object

Returns: a pointer to the container name

◆ pn_connection_set_container()

void pn_connection_set_container	(	pn_connection_t *	connection,
		const char *	container
	)

Set the AMQP Container name advertised by a connection object.

Parameters

[in]	connection	the connection object
[in]	container	the container name

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

◆ pn_connection_set_user()

void pn_connection_set_user	(	pn_connection_t *	connection,
		const char *	user
	)

Set the authentication username for a client connection.

It is necessary to set the username and password before binding the connection to a transport and it isn't allowed to change them after the binding.

If not set then no authentication will be negotiated unless the client sasl layer is explicitly created (this would be for something like Kerberos where the credentials are implicit in the environment, or to explicitly use the ANONYMOUS SASL mechanism)

Parameters

[in]	connection	the connection
[in]	user	the username

◆ pn_connection_set_password()

void pn_connection_set_password	(	pn_connection_t *	connection,
		const char *	password
	)

Set the authentication password for a client connection.

It is necessary to set the username and password before binding the connection to a transport and it isn't allowed to change them after the binding.

Note that the password is write only and has no accessor as the underlying implementation should be zeroing the password after use to avoid the password being present in memory longer than necessary

Parameters

[in]	connection	the connection
[in]	password	the password corresponding to the username - this will be copied and zeroed out after use

◆ pn_connection_set_authorization()

void pn_connection_set_authorization	(	pn_connection_t *	connection,
		const char *	authzid
	)

Set the authorization id for a client connection.

It is necessary to set the authorization before binding the connection to a transport and it isn't allowed to change it after the binding.

This is only useful if the negotiated sasl mechanism supports transporting an authorization id separate from the authentication user.

By default all mechanisms will consider the requested authorization as identical to the authentication if it is not supplied.

Parameters

[in]	connection	the connection
[in]	authzid	the authorization id

◆ pn_connection_get_user()

const char * pn_connection_get_user ( pn_connection_t * connection )

Get the authentication username for a client connection.

Parameters

[in] connection the connection

Returns: the username passed into the connection

◆ pn_connection_get_authorization()

const char * pn_connection_get_authorization ( pn_connection_t * connection )

Get the authorization id for a client connection.

Parameters

[in] connection the connection

Returns: the authorization passed into the connection

◆ pn_connection_get_hostname()

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] connection the connection object

Returns: a pointer to the hostname

◆ pn_connection_set_hostname()

void pn_connection_set_hostname	(	pn_connection_t *	connection,
		const char *	hostname
	)

Set the name of the virtual host (either fully qualified or relative) to which this connection is connecting to.

This information may be used by the remote peer to determine the correct back-end service to connect the client to. This value will be sent in the Open performative, and will be used by SSL and SASL layers to identify the peer.

Note: Note: the virtual host string is passed verbatim, it is not parsed as a URL or modified in any way. It should not contain numeric IP addresses or port numbers unless that is what you intend to send as the virtual host name

Parameters

[in]	connection	the connection object
[in]	hostname	the virtual host name

◆ pn_connection_remote_container()

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] connection the connection object

Returns: a pointer to the remote container name

◆ pn_connection_remote_hostname()

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] connection the connection object

Returns: a pointer to the remote hostname

◆ pn_connection_offered_capabilities()

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 capabilities 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] connection the connection object

Returns: a pointer to a pn_data_t representing the offered capabilities

◆ pn_connection_desired_capabilities()

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 capabilities 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] connection the connection object

Returns: a pointer to a pn_data_t representing the desired capabilities

◆ pn_connection_properties()

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] connection the connection object

Returns: a pointer to a pn_data_t representing the connection properties

◆ pn_connection_remote_offered_capabilities()

pn_data_t * pn_connection_remote_offered_capabilities ( pn_connection_t * connection )

Access the AMQP offered capabilities 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] connection the connection object

Returns: the remote offered capabilities

◆ pn_connection_remote_desired_capabilities()

pn_data_t * pn_connection_remote_desired_capabilities ( pn_connection_t * connection )

Access the AMQP desired capabilities 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] connection the connection object

Returns: the remote desired capabilities

◆ pn_connection_remote_properties()

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] connection the connection object

Returns: the remote connection properties

◆ pn_connection_transport()

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] connection the connection object

Returns: the transport bound to a connection, or NULL if the connection is unbound

Macros

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ pn_state_t

◆ pn_connection_t

Function Documentation

◆ pn_connection()

◆ pn_connection_free()

◆ pn_connection_release()

◆ pn_connection_error()

◆ pn_connection_collect()

◆ pn_connection_collector()

◆ pn_connection_get_context()

◆ pn_connection_set_context()

◆ pn_connection_attachments()

◆ pn_connection_state()

◆ pn_connection_open()

◆ pn_connection_close()

◆ pn_connection_reset()

◆ pn_connection_condition()

◆ pn_connection_remote_condition()

◆ pn_connection_get_container()

◆ pn_connection_set_container()

◆ pn_connection_set_user()

◆ pn_connection_set_password()

◆ pn_connection_set_authorization()

◆ pn_connection_get_user()

◆ pn_connection_get_authorization()

◆ pn_connection_get_hostname()

◆ pn_connection_set_hostname()

◆ pn_connection_remote_container()

◆ pn_connection_remote_hostname()

◆ pn_connection_offered_capabilities()

◆ pn_connection_desired_capabilities()

◆ pn_connection_properties()

◆ pn_connection_remote_offered_capabilities()

◆ pn_connection_remote_desired_capabilities()

◆ pn_connection_remote_properties()

◆ pn_connection_transport()