API for the Driver Layer. More...

#include <proton/import_export.h>
#include <proton/error.h>
#include <proton/engine.h>
#include <proton/sasl.h>
#include <proton/selectable.h>
#include <proton/ssl.h>

Typedefs
typedef struct pn_driver_t	pn_driver_t

typedef struct pn_listener_t	pn_listener_t

typedef struct pn_connector_t	pn_connector_t

Enumerations
enum	pn_activate_criteria_t { PN_CONNECTOR_WRITABLE, PN_CONNECTOR_READABLE }

Functions
PN_EXTERN pn_driver_t *	pn_driver (void)
	Construct a driver. More...

PN_EXTERN int	pn_driver_errno (pn_driver_t *d)
	Return the most recent error code. More...

PN_EXTERN const char *	pn_driver_error (pn_driver_t *d)
	Return the most recent error text for d. More...

PN_EXTERN void	pn_driver_trace (pn_driver_t *driver, pn_trace_t trace)
	Set the tracing level for the given driver. More...

PN_EXTERN int	pn_driver_wakeup (pn_driver_t *driver)
	Force pn_driver_wait() to return. More...

PN_EXTERN int	pn_driver_wait (pn_driver_t *driver, int timeout)
	Wait for an active connector or listener. More...

PN_EXTERN pn_listener_t *	pn_driver_listener (pn_driver_t *driver)
	Get the next listener with pending data in the driver. More...

PN_EXTERN pn_connector_t *	pn_driver_connector (pn_driver_t *driver)
	Get the next active connector in the driver. More...

PN_EXTERN void	pn_driver_free (pn_driver_t *driver)
	Free the driver allocated via pn_driver, and all associated listeners and connectors. More...

PN_EXTERN pn_listener_t *	pn_listener (pn_driver_t driver, const char host, const char port, void context)
	pn_listener - the server API More...

PN_EXTERN pn_listener_t *	pn_listener_head (pn_driver_t *driver)
	Access the head listener for a driver. More...

PN_EXTERN pn_listener_t *	pn_listener_next (pn_listener_t *listener)
	Access the next listener. More...

PN_EXTERN void	pn_listener_trace (pn_listener_t *listener, pn_trace_t trace)

PN_EXTERN pn_connector_t *	pn_listener_accept (pn_listener_t *listener)
	Accept a connection that is pending on the listener. More...

PN_EXTERN void *	pn_listener_context (pn_listener_t *listener)
	Access the application context that is associated with the listener. More...

PN_EXTERN void	pn_listener_set_context (pn_listener_t listener, void context)

PN_EXTERN void	pn_listener_close (pn_listener_t *listener)
	Close the socket used by the listener. More...

PN_EXTERN void	pn_listener_free (pn_listener_t *listener)
	Frees the given listener. More...

PN_EXTERN pn_connector_t *	pn_connector (pn_driver_t driver, const char host, const char port, void context)
	pn_connector - the client API More...

PN_EXTERN pn_connector_t *	pn_connector_head (pn_driver_t *driver)
	Access the head connector for a driver. More...

PN_EXTERN pn_connector_t *	pn_connector_next (pn_connector_t *connector)
	Access the next connector. More...

PN_EXTERN void	pn_connector_trace (pn_connector_t *connector, pn_trace_t trace)
	Set the tracing level for the given connector. More...

PN_EXTERN void	pn_connector_process (pn_connector_t *connector)
	Service the given connector. More...

PN_EXTERN pn_listener_t *	pn_connector_listener (pn_connector_t *connector)
	Access the listener which opened this connector. More...

PN_EXTERN pn_sasl_t *	pn_connector_sasl (pn_connector_t *connector)
	Access the Authentication and Security context of the connector. More...

PN_EXTERN pn_connection_t *	pn_connector_connection (pn_connector_t *connector)
	Access the AMQP Connection associated with the connector. More...

PN_EXTERN void	pn_connector_set_connection (pn_connector_t connector, pn_connection_t connection)
	Assign the AMQP Connection associated with the connector. More...

PN_EXTERN void *	pn_connector_context (pn_connector_t *connector)
	Access the application context that is associated with the connector. More...

PN_EXTERN void	pn_connector_set_context (pn_connector_t connector, void context)
	Assign a new application context to the connector. More...

PN_EXTERN const char *	pn_connector_name (const pn_connector_t *connector)
	Access the name of the connector. More...

PN_EXTERN pn_transport_t *	pn_connector_transport (pn_connector_t *connector)
	Access the transport used by this connector. More...

PN_EXTERN void	pn_connector_close (pn_connector_t *connector)
	Close the socket used by the connector. More...

PN_EXTERN bool	pn_connector_closed (pn_connector_t *connector)
	Determine if the connector is closed. More...

PN_EXTERN void	pn_connector_free (pn_connector_t *connector)
	Destructor for the given connector. More...

PN_EXTERN void	pn_connector_activate (pn_connector_t *connector, pn_activate_criteria_t criteria)
	Activate a connector when a criteria is met. More...

PN_EXTERN bool	pn_connector_activated (pn_connector_t *connector, pn_activate_criteria_t criteria)
	Return the activation status of the connector for a criteria. More...

Detailed Description

API for the Driver Layer.

The driver library provides a simple implementation of a driver for the proton engine. A driver is responsible for providing input, output, and tick events to the bottom half of the engine API. See pn_transport_input, pn_transport_output, and pn_transport_tick. The driver also provides an interface for the application to access the top half of the API when the state of the engine may have changed due to I/O or timing events. Additionally the driver incorporates the SASL engine as well in order to provide a complete network stack: AMQP over SASL over TCP.

Typedef Documentation

typedef struct pn_connector_t pn_connector_t

typedef struct pn_driver_t pn_driver_t

typedef struct pn_listener_t pn_listener_t

Enumeration Type Documentation

enum pn_activate_criteria_t

Enumerator
PN_CONNECTOR_WRITABLE
PN_CONNECTOR_READABLE

Function Documentation

PN_EXTERN pn_connector_t* pn_connector	(	pn_driver_t *	driver,
		const char *	host,
		const char *	port,
		void *	context
	)

pn_connector - the client API

Construct a connector to the given remote address.

Parameters

[in]	driver	owner of this connection.
[in]	host	remote host to connect to.
[in]	port	remote port to connect to.
[in]	context	application supplied, can be accessed via pn_connector_context()

Returns: a new connector to the given remote, or NULL on error.

PN_EXTERN void pn_connector_activate	(	pn_connector_t *	connector,
		pn_activate_criteria_t	criteria
	)

Activate a connector when a criteria is met.

Set a criteria for a connector (i.e. it's transport is writable) that, once met, the connector shall be placed in the driver's work queue.

Parameters

[in]	connector	The connector object to activate
[in]	criteria	The criteria that must be met prior to activating the connector

PN_EXTERN bool pn_connector_activated	(	pn_connector_t *	connector,
		pn_activate_criteria_t	criteria
	)

Return the activation status of the connector for a criteria.

Return the activation status (i.e. readable, writable) for the connector. This function has the side-effect of canceling the activation of the criteria.

Please note that this function must not be used for normal AMQP connectors. It is only used for connectors created so the driver can track non-AMQP file descriptors. Such connectors are never passed into pn_connector_process.

Parameters

[in]	connector	The connector object to activate
[in]	criteria	The criteria to test. "Is this the reason the connector appeared in the work list?"

Returns: true iff the criteria is activated on the connector.

PN_EXTERN void pn_connector_close ( pn_connector_t * connector )

Close the socket used by the connector.

Parameters

[in] connector the connector whose socket will be closed

PN_EXTERN bool pn_connector_closed ( pn_connector_t * connector )

Determine if the connector is closed.

Returns: True if closed, otherwise false

PN_EXTERN pn_connection_t* pn_connector_connection ( pn_connector_t * connector )

Access the AMQP Connection associated with the connector.

Parameters

[in] connector the connector whose connection will be returned

Returns: the connection context for the connector, or NULL if none

PN_EXTERN void* pn_connector_context ( pn_connector_t * connector )

Access the application context that is associated with the connector.

Parameters

[in] connector the connector whose context is to be returned.

Returns: the application context that was passed to pn_connector() or pn_connector_fd()

PN_EXTERN void pn_connector_free ( pn_connector_t * connector )

Destructor for the given connector.

Assumes the connector's socket has been closed prior to call.

Parameters

[in] connector the connector object to free. No longer valid on return

PN_EXTERN pn_connector_t* pn_connector_head ( pn_driver_t * driver )

Access the head connector for a driver.

Parameters

[in] driver the driver whose head connector will be returned

Returns: the head connector for driver or NULL if there is none

PN_EXTERN pn_listener_t* pn_connector_listener ( pn_connector_t * connector )

Access the listener which opened this connector.

Parameters

[in] connector connector whose listener will be returned.

Returns: the listener which created this connector, or NULL if the connector has no listener (e.g. an outbound client connection)

PN_EXTERN const char* pn_connector_name ( const pn_connector_t * connector )

Access the name of the connector.

Parameters

[in] connector the connector which will hole the name

Returns: the name of the connector in the form of a null-terminated character string.

PN_EXTERN pn_connector_t* pn_connector_next ( pn_connector_t * connector )

Access the next connector.

Parameters

[in] connector the connector whose next connector will be returned

Returns: the next connector

PN_EXTERN void pn_connector_process ( pn_connector_t * connector )

Service the given connector.

Handle any inbound data, outbound data, or timing events pending on the connector.

Parameters

[in] connector the connector to process.

PN_EXTERN pn_sasl_t* pn_connector_sasl ( pn_connector_t * connector )

Access the Authentication and Security context of the connector.

Parameters

[in] connector connector whose security context will be returned

Returns: the Authentication and Security context for the connector, or NULL if none

PN_EXTERN void pn_connector_set_connection	(	pn_connector_t *	connector,
		pn_connection_t *	connection
	)

Assign the AMQP Connection associated with the connector.

Parameters

[in]	connector	the connector whose connection will be set.
[in]	connection	the connection to associate with the connector

PN_EXTERN void pn_connector_set_context	(	pn_connector_t *	connector,
		void *	context
	)

Assign a new application context to the connector.

Parameters

[in]	connector	the connector which will hold the context.
[in]	context	new application context to associate with the connector

PN_EXTERN void pn_connector_trace	(	pn_connector_t *	connector,
		pn_trace_t	trace
	)

Set the tracing level for the given connector.

Parameters

[in]	connector	the connector to trace
[in]	trace	the trace level to use.

PN_EXTERN pn_transport_t* pn_connector_transport ( pn_connector_t * connector )

Access the transport used by this connector.

Parameters

[in] connector connector whose transport will be returned

Returns: the transport, or NULL if none

PN_EXTERN pn_driver_t* pn_driver ( void )

Construct a driver.

Call pn_driver_free() to release the driver object.

Returns: new driver object, NULL if error

PN_EXTERN pn_connector_t* pn_driver_connector ( pn_driver_t * driver )

Get the next active connector in the driver.

Returns the next connector with pending inbound data, available capacity for outbound data, or pending tick.

Parameters

[in] driver the driver

Returns: NULL if no active connector available

PN_EXTERN int pn_driver_errno ( pn_driver_t * d )

Return the most recent error code.

Parameters

[in] d the driver

Returns: the most recent error text for d

PN_EXTERN const char* pn_driver_error ( pn_driver_t * d )

Return the most recent error text for d.

Parameters

[in] d the driver

Returns: the most recent error text for d

PN_EXTERN void pn_driver_free ( pn_driver_t * driver )

Free the driver allocated via pn_driver, and all associated listeners and connectors.

Parameters

[in] driver the driver to free, no longer valid on return

PN_EXTERN pn_listener_t* pn_driver_listener ( pn_driver_t * driver )

Get the next listener with pending data in the driver.

Parameters

[in] driver the driver

Returns: NULL if no active listener available

PN_EXTERN void pn_driver_trace	(	pn_driver_t *	driver,
		pn_trace_t	trace
	)

Set the tracing level for the given driver.

Parameters

[in]	driver	the driver to trace
[in]	trace	the trace level to use.

Todo:: pn_trace_t needs documentation

PN_EXTERN int pn_driver_wait	(	pn_driver_t *	driver,
		int	timeout
	)

Wait for an active connector or listener.

Parameters

[in]	driver	the driver to wait on
[in]	timeout	maximum time in milliseconds to wait, -1 means infinite wait

Returns: zero on success, an error code on failure

PN_EXTERN int pn_driver_wakeup ( pn_driver_t * driver )

Force pn_driver_wait() to return.

Parameters

[in] driver the driver to wake up

Returns: zero on success, an error code on failure

PN_EXTERN pn_listener_t* pn_listener	(	pn_driver_t *	driver,
		const char *	host,
		const char *	port,
		void *	context
	)

pn_listener - the server API

Construct a listener for the given address.

Parameters

[in]	driver	driver that will 'own' this listener
[in]	host	local host address to listen on
[in]	port	local port to listen on
[in]	context	application-supplied, can be accessed via pn_listener_context()

Returns: a new listener on the given host:port, NULL if error

PN_EXTERN pn_connector_t* pn_listener_accept ( pn_listener_t * listener )

Accept a connection that is pending on the listener.

Parameters

[in] listener the listener to accept the connection on

Returns: a new connector for the remote, or NULL on error

PN_EXTERN void pn_listener_close ( pn_listener_t * listener )

Close the socket used by the listener.

Parameters

[in] listener the listener whose socket will be closed.

PN_EXTERN void* pn_listener_context ( pn_listener_t * listener )

Access the application context that is associated with the listener.

Parameters

[in] listener the listener whose context is to be returned

Returns: the application context that was passed to pn_listener() or pn_listener_fd()

PN_EXTERN void pn_listener_free ( pn_listener_t * listener )

Frees the given listener.

Assumes the listener's socket has been closed prior to call.

Parameters

[in] listener the listener object to free, no longer valid on return

PN_EXTERN pn_listener_t* pn_listener_head ( pn_driver_t * driver )

Access the head listener for a driver.

Parameters

[in] driver the driver whose head listener will be returned

Returns: the head listener for driver or NULL if there is none

PN_EXTERN pn_listener_t* pn_listener_next ( pn_listener_t * listener )

Access the next listener.

Parameters

[in] listener the listener whose next listener will be returned

Returns: the next listener

PN_EXTERN void pn_listener_set_context	(	pn_listener_t *	listener,
		void *	context
	)

PN_EXTERN void pn_listener_trace	(	pn_listener_t *	listener,
		pn_trace_t	trace
	)

Todo:: pn_listener_trace needs documentation

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation