proton
0
|
API for the Driver Layer. More...
#include <proton/error.h>
#include <proton/engine.h>
#include <proton/sasl.h>
#include <proton/ssl.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_driver_t * | pn_driver (void) |
Construct a driver. | |
int | pn_driver_errno (pn_driver_t *d) |
Return the most recent error code. | |
const char * | pn_driver_error (pn_driver_t *d) |
Return the most recent error text for d. | |
void | pn_driver_trace (pn_driver_t *driver, pn_trace_t trace) |
Set the tracing level for the given driver. | |
int | pn_driver_wakeup (pn_driver_t *driver) |
Force pn_driver_wait() to return. | |
int | pn_driver_wait (pn_driver_t *driver, int timeout) |
Wait for an active connector or listener. | |
pn_listener_t * | pn_driver_listener (pn_driver_t *driver) |
Get the next listener with pending data in the driver. | |
pn_connector_t * | pn_driver_connector (pn_driver_t *driver) |
Get the next active connector in the driver. | |
void | pn_driver_free (pn_driver_t *driver) |
Free the driver allocated via pn_driver, and all associated listeners and connectors. | |
pn_listener_t * | pn_listener (pn_driver_t *driver, const char *host, const char *port, void *context) |
pn_listener - the server API | |
pn_listener_t * | pn_listener_fd (pn_driver_t *driver, int fd, void *context) |
Create a listener using the existing file descriptor. | |
pn_listener_t * | pn_listener_head (pn_driver_t *driver) |
Access the head listener for a driver. | |
pn_listener_t * | pn_listener_next (pn_listener_t *listener) |
Access the next listener. | |
void | pn_listener_trace (pn_listener_t *listener, pn_trace_t trace) |
pn_connector_t * | pn_listener_accept (pn_listener_t *listener) |
Accept a connection that is pending on the listener. | |
void * | pn_listener_context (pn_listener_t *listener) |
Access the application context that is associated with the listener. | |
void | pn_listener_set_context (pn_listener_t *listener, void *context) |
void | pn_listener_close (pn_listener_t *listener) |
Close the socket used by the listener. | |
void | pn_listener_free (pn_listener_t *listener) |
Frees the given listener. | |
pn_connector_t * | pn_connector (pn_driver_t *driver, const char *host, const char *port, void *context) |
pn_connector - the client API | |
pn_connector_t * | pn_connector_fd (pn_driver_t *driver, int fd, void *context) |
Create a connector using the existing file descriptor. | |
pn_connector_t * | pn_connector_head (pn_driver_t *driver) |
Access the head connector for a driver. | |
pn_connector_t * | pn_connector_next (pn_connector_t *connector) |
Access the next connector. | |
void | pn_connector_trace (pn_connector_t *connector, pn_trace_t trace) |
Set the tracing level for the given connector. | |
void | pn_connector_process (pn_connector_t *connector) |
Service the given connector. | |
pn_listener_t * | pn_connector_listener (pn_connector_t *connector) |
Access the listener which opened this connector. | |
pn_sasl_t * | pn_connector_sasl (pn_connector_t *connector) |
Access the Authentication and Security context of the connector. | |
pn_connection_t * | pn_connector_connection (pn_connector_t *connector) |
Access the AMQP Connection associated with the connector. | |
void | pn_connector_set_connection (pn_connector_t *connector, pn_connection_t *connection) |
Assign the AMQP Connection associated with the connector. | |
void * | pn_connector_context (pn_connector_t *connector) |
Access the application context that is associated with the connector. | |
void | pn_connector_set_context (pn_connector_t *connector, void *context) |
Assign a new application context to the connector. | |
pn_transport_t * | pn_connector_transport (pn_connector_t *connector) |
Access the transport used by this connector. | |
void | pn_connector_close (pn_connector_t *connector) |
Close the socket used by the connector. | |
bool | pn_connector_closed (pn_connector_t *connector) |
Determine if the connector is closed. | |
void | pn_connector_free (pn_connector_t *connector) |
Destructor for the given connector. | |
void | pn_connector_activate (pn_connector_t *connector, pn_activate_criteria_t criteria) |
Activate a connector when a criteria is met. | |
bool | pn_connector_activated (pn_connector_t *connector, pn_activate_criteria_t criteria) |
Return the activation status of the connector for a criteria. | |
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 struct pn_connector_t pn_connector_t |
typedef struct pn_driver_t pn_driver_t |
typedef struct pn_listener_t pn_listener_t |
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.
[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() |
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.
[in] | connector | The connector object to activate |
[in] | criteria | The criteria that must be met prior to activating the connector |
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.
[in] | connector | The connector object to activate |
[in] | criteria | The criteria to test. "Is this the reason the connector appeared in the work list?" |
void pn_connector_close | ( | pn_connector_t * | connector | ) |
Close the socket used by the connector.
[in] | connector | the connector whose socket will be closed |
bool pn_connector_closed | ( | pn_connector_t * | connector | ) |
Determine if the connector is closed.
pn_connection_t* pn_connector_connection | ( | pn_connector_t * | connector | ) |
Access the AMQP Connection associated with the connector.
[in] | connector | the connector whose connection will be returned |
void* pn_connector_context | ( | pn_connector_t * | connector | ) |
Access the application context that is associated with the connector.
[in] | connector | the connector whose context is to be returned. |
pn_connector_t* pn_connector_fd | ( | pn_driver_t * | driver, |
int | fd, | ||
void * | context | ||
) |
Create a connector using the existing file descriptor.
[in] | driver | driver that will 'own' this connector. |
[in] | fd | existing file descriptor to use for this connector. |
[in] | context | application-supplied, can be accessed via pn_connector_context() |
void pn_connector_free | ( | pn_connector_t * | connector | ) |
Destructor for the given connector.
Assumes the connector's socket has been closed prior to call.
[in] | connector | the connector object to free. No longer valid on return |
pn_connector_t* pn_connector_head | ( | pn_driver_t * | driver | ) |
Access the head connector for a driver.
[in] | driver | the driver whose head connector will be returned |
pn_listener_t* pn_connector_listener | ( | pn_connector_t * | connector | ) |
Access the listener which opened this connector.
[in] | connector | connector whose listener will be returned. |
pn_connector_t* pn_connector_next | ( | pn_connector_t * | connector | ) |
Access the next connector.
[in] | connector | the connector whose next connector will be returned |
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.
[in] | connector | the connector to process. |
pn_sasl_t* pn_connector_sasl | ( | pn_connector_t * | connector | ) |
Access the Authentication and Security context of the connector.
[in] | connector | connector whose security context will be returned |
void pn_connector_set_connection | ( | pn_connector_t * | connector, |
pn_connection_t * | connection | ||
) |
Assign the AMQP Connection associated with the connector.
[in] | connector | the connector whose connection will be set. |
[in] | connection | the connection to associate with the connector |
void pn_connector_set_context | ( | pn_connector_t * | connector, |
void * | context | ||
) |
Assign a new application context to the connector.
[in] | connector | the connector which will hold the context. |
[in] | context | new application context to associate with the connector |
void pn_connector_trace | ( | pn_connector_t * | connector, |
pn_trace_t | trace | ||
) |
Set the tracing level for the given connector.
[in] | connector | the connector to trace |
[in] | trace | the trace level to use. |
pn_transport_t* pn_connector_transport | ( | pn_connector_t * | connector | ) |
Access the transport used by this connector.
[in] | connector | connector whose transport will be returned |
pn_driver_t* pn_driver | ( | void | ) |
Construct a driver.
Call pn_driver_free() to release the driver object.
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.
[in] | driver | the driver |
int pn_driver_errno | ( | pn_driver_t * | d | ) |
Return the most recent error code.
[in] | d | the driver |
const char* pn_driver_error | ( | pn_driver_t * | d | ) |
Return the most recent error text for d.
[in] | d | the driver |
void pn_driver_free | ( | pn_driver_t * | driver | ) |
Free the driver allocated via pn_driver, and all associated listeners and connectors.
[in] | driver | the driver to free, no longer valid on return |
pn_listener_t* pn_driver_listener | ( | pn_driver_t * | driver | ) |
Get the next listener with pending data in the driver.
[in] | driver | the driver |
void pn_driver_trace | ( | pn_driver_t * | driver, |
pn_trace_t | trace | ||
) |
Set the tracing level for the given driver.
[in] | driver | the driver to trace |
[in] | trace | the trace level to use. |
int pn_driver_wait | ( | pn_driver_t * | driver, |
int | timeout | ||
) |
Wait for an active connector or listener.
[in] | driver | the driver to wait on |
[in] | timeout | maximum time in milliseconds to wait, -1 means infinite wait |
int pn_driver_wakeup | ( | pn_driver_t * | driver | ) |
Force pn_driver_wait() to return.
[in] | driver | the driver to wake up |
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.
[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() |
pn_connector_t* pn_listener_accept | ( | pn_listener_t * | listener | ) |
Accept a connection that is pending on the listener.
[in] | listener | the listener to accept the connection on |
void pn_listener_close | ( | pn_listener_t * | listener | ) |
Close the socket used by the listener.
[in] | listener | the listener whose socket will be closed. |
void* pn_listener_context | ( | pn_listener_t * | listener | ) |
Access the application context that is associated with the listener.
[in] | listener | the listener whose context is to be returned |
pn_listener_t* pn_listener_fd | ( | pn_driver_t * | driver, |
int | fd, | ||
void * | context | ||
) |
Create a listener using the existing file descriptor.
[in] | driver | driver that will 'own' this listener |
[in] | fd | existing file descriptor for listener to listen on |
[in] | context | application-supplied, can be accessed via pn_listener_context() |
void pn_listener_free | ( | pn_listener_t * | listener | ) |
Frees the given listener.
Assumes the listener's socket has been closed prior to call.
[in] | listener | the listener object to free, no longer valid on return |
pn_listener_t* pn_listener_head | ( | pn_driver_t * | driver | ) |
Access the head listener for a driver.
[in] | driver | the driver whose head listener will be returned |
pn_listener_t* pn_listener_next | ( | pn_listener_t * | listener | ) |
Access the next listener.
[in] | listener | the listener whose next listener will be returned |
void pn_listener_set_context | ( | pn_listener_t * | listener, |
void * | context | ||
) |
void pn_listener_trace | ( | pn_listener_t * | listener, |
pn_trace_t | trace | ||
) |