C AMQP Protocol Engine API  0.4
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
driver.h File Reference
#include <proton/import_export.h>
#include <proton/error.h>
#include <proton/engine.h>
#include <proton/sasl.h>
#include <proton/ssl.h>
Include dependency graph for driver.h:

Go to the source code of this file.

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_tpn_driver (void)
 
PN_EXTERN int pn_driver_errno (pn_driver_t *d)
 
PN_EXTERN const char * pn_driver_error (pn_driver_t *d)
 
PN_EXTERN void pn_driver_trace (pn_driver_t *driver, pn_trace_t trace)
 
PN_EXTERN int pn_driver_wakeup (pn_driver_t *driver)
 
PN_EXTERN int pn_driver_wait (pn_driver_t *driver, int timeout)
 
PN_EXTERN pn_listener_tpn_driver_listener (pn_driver_t *driver)
 
PN_EXTERN pn_connector_tpn_driver_connector (pn_driver_t *driver)
 
PN_EXTERN void pn_driver_free (pn_driver_t *driver)
 
PN_EXTERN pn_listener_tpn_listener (pn_driver_t *driver, const char *host, const char *port, void *context)
 
PN_EXTERN pn_listener_tpn_listener_head (pn_driver_t *driver)
 
PN_EXTERN pn_listener_tpn_listener_next (pn_listener_t *listener)
 
PN_EXTERN void pn_listener_trace (pn_listener_t *listener, pn_trace_t trace)
 
PN_EXTERN pn_connector_tpn_listener_accept (pn_listener_t *listener)
 
PN_EXTERN void * pn_listener_context (pn_listener_t *listener)
 
PN_EXTERN void pn_listener_set_context (pn_listener_t *listener, void *context)
 
PN_EXTERN void pn_listener_close (pn_listener_t *listener)
 
PN_EXTERN void pn_listener_free (pn_listener_t *listener)
 
PN_EXTERN pn_connector_tpn_connector (pn_driver_t *driver, const char *host, const char *port, void *context)
 
PN_EXTERN pn_connector_tpn_connector_head (pn_driver_t *driver)
 
PN_EXTERN pn_connector_tpn_connector_next (pn_connector_t *connector)
 
PN_EXTERN void pn_connector_trace (pn_connector_t *connector, pn_trace_t trace)
 
PN_EXTERN void pn_connector_process (pn_connector_t *connector)
 
PN_EXTERN pn_listener_tpn_connector_listener (pn_connector_t *connector)
 
PN_EXTERN pn_sasl_tpn_connector_sasl (pn_connector_t *connector)
 
PN_EXTERN pn_connection_tpn_connector_connection (pn_connector_t *connector)
 
PN_EXTERN void pn_connector_set_connection (pn_connector_t *connector, pn_connection_t *connection)
 
PN_EXTERN void * pn_connector_context (pn_connector_t *connector)
 
PN_EXTERN void pn_connector_set_context (pn_connector_t *connector, void *context)
 
PN_EXTERN pn_transport_tpn_connector_transport (pn_connector_t *connector)
 
PN_EXTERN void pn_connector_close (pn_connector_t *connector)
 
PN_EXTERN bool pn_connector_closed (pn_connector_t *connector)
 
PN_EXTERN void pn_connector_free (pn_connector_t *connector)
 
PN_EXTERN void pn_connector_activate (pn_connector_t *connector, pn_activate_criteria_t criteria)
 
PN_EXTERN bool pn_connector_activated (pn_connector_t *connector, pn_activate_criteria_t criteria)
 

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_driver_t pn_driver_t
typedef struct pn_listener_t pn_listener_t

Enumeration Type Documentation

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]driverowner of this connection.
[in]hostremote host to connect to.
[in]portremote port to connect to.
[in]contextapplication 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]connectorThe connector object to activate
[in]criteriaThe 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]connectorThe connector object to activate
[in]criteriaThe 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]connectorthe 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]connectorthe 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]connectorthe 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]connectorthe 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]driverthe 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]connectorconnector 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 pn_connector_t* pn_connector_next ( pn_connector_t connector)

Access the next connector.

Parameters
[in]connectorthe 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]connectorthe 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]connectorconnector 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]connectorthe connector whose connection will be set.
[in]connectionthe 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]connectorthe connector which will hold the context.
[in]contextnew 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]connectorthe connector to trace
[in]tracethe 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]connectorconnector 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]driverthe 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]dthe 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]dthe 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]driverthe 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]driverthe 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]driverthe driver to trace
[in]tracethe 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]driverthe driver to wait on
[in]timeoutmaximum 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]driverthe 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]driverdriver that will 'own' this listener
[in]hostlocal host address to listen on
[in]portlocal port to listen on
[in]contextapplication-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]listenerthe 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]listenerthe 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]listenerthe 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]listenerthe 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]driverthe 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]listenerthe 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