**Unsettled API** - An API for low-level IO integration. More...
Classes | |
struct | pn_connection_driver_t |
The elements needed to drive AMQP IO and events. More... | |
Defines | |
#define | PN_TRANSPORT_WRITE_CLOSED |
The write side of the transport is closed, it will no longer produce bytes to write to external IO. | |
#define | PN_TRANSPORT_READ_CLOSED |
The read side of the transport is closed, it will no longer read bytes from external IO. | |
Functions | |
int | pn_connection_driver_init (pn_connection_driver_t *, pn_connection_t *, pn_transport_t *) |
Set connection and transport to the provided values, or create a new pn_connection_t or pn_transport_t if either is NULL. | |
int | pn_connection_driver_bind (pn_connection_driver_t *d) |
Force binding of the transport. | |
void | pn_connection_driver_destroy (pn_connection_driver_t *) |
Unbind, release and free the connection and transport. | |
pn_connection_t * | pn_connection_driver_release_connection (pn_connection_driver_t *d) |
Disassociate the driver's connection from its transport and collector and sets d->connection = NULL. | |
pn_rwbytes_t | pn_connection_driver_read_buffer (pn_connection_driver_t *) |
Get the read buffer. | |
void | pn_connection_driver_read_done (pn_connection_driver_t *, size_t n) |
Process the first n bytes of data in pn_connection_driver_read_buffer() and reclaim the buffer space. | |
void | pn_connection_driver_read_close (pn_connection_driver_t *) |
Close the read side. | |
bool | pn_connection_driver_read_closed (pn_connection_driver_t *) |
True if read side is closed. | |
pn_bytes_t | pn_connection_driver_write_buffer (pn_connection_driver_t *) |
Get the write buffer. | |
void | pn_connection_driver_write_done (pn_connection_driver_t *, size_t n) |
Call when the first n bytes of pn_connection_driver_write_buffer() have been written to IO. | |
void | pn_connection_driver_write_close (pn_connection_driver_t *) |
Close the write side. | |
bool | pn_connection_driver_write_closed (pn_connection_driver_t *) |
True if write side is closed. | |
void | pn_connection_driver_close (pn_connection_driver_t *c) |
Close both sides. | |
pn_event_t * | pn_connection_driver_next_event (pn_connection_driver_t *) |
Get the next event to handle. | |
bool | pn_connection_driver_has_event (pn_connection_driver_t *) |
True if pn_connection_driver_next_event() will return a non-NULL event. | |
bool | pn_connection_driver_finished (pn_connection_driver_t *) |
Return true if the the driver is closed for reading and writing and there are no more events. | |
void | pn_connection_driver_errorf (pn_connection_driver_t *d, const char *name, const char *fmt,...) |
Set transport error. | |
void | pn_connection_driver_verrorf (pn_connection_driver_t *d, const char *name, const char *fmt, va_list) |
Set transport error via a va_list, see pn_connection_driver_errorf(). | |
pn_connection_driver_t * | pn_event_batch_connection_driver (pn_event_batch_t *batch) |
If batch is part of a connection_driver, return the connection_driver address, else return NULL. | |
void | pn_connection_driver_log (pn_connection_driver_t *d, const char *msg) |
**Deprecated** - Use pn_transport_log(). | |
void | pn_connection_driver_logf (pn_connection_driver_t *d, const char *fmt,...) |
**Deprecated** - Use pn_transport_logf(). | |
void | pn_connection_driver_vlogf (pn_connection_driver_t *d, const char *fmt, va_list ap) |
**Deprecated** - Use pn_transport_vlogf(). |
**Unsettled API** - An API for low-level IO integration.
Associate a Connection and Transport with AMQP byte streams from any source.
The `pn_connection_driver_*` functions provide a simplified API and extra logic to use pn_connection_t and pn_transport_t as a unit. You can also access them directly for features that do not have `pn_connection_driver_*` functions.
The driver buffers events and data. You should run it until pn_connection_driver_finished() is true, to ensure all reading, writing, and event handling (including `ERROR` and `FINAL` events) is finished.
## Error handling
The `pn_connection_driver_*` functions do not return an error code. IO errors are set on the transport condition and are returned as a `PN_TRANSPORT_ERROR`. The integration code can set errors using pn_connection_driver_errorf().
## IO patterns
This API supports asynchronous, proactive, non-blocking and reactive IO. An integration does not have to follow the dispatch-read-write sequence above, but note that you should handle all available events before calling pn_connection_driver_read_buffer() and check that `size` is non-zero before starting a blocking or asynchronous read call. A `read` started while there are unprocessed `CLOSE` events in the buffer may never complete.
AMQP is a full-duplex, asynchronous protocol. The "read" and "write" sides of an AMQP connection can close separately.
## Thread safety
The Connection driver types are not thread safe, but each connection and its associated types form an independent unit. Different connections can be processed concurrently by different threads.
#define PN_TRANSPORT_WRITE_CLOSED |
The write side of the transport is closed, it will no longer produce bytes to write to external IO.
Synonynm for PN_TRANSPORT_HEAD_CLOSED
#define PN_TRANSPORT_READ_CLOSED |
The read side of the transport is closed, it will no longer read bytes from external IO.
Alisas for PN_TRANSPORT_TAIL_CLOSED
int pn_connection_driver_init | ( | pn_connection_driver_t * | , | |
pn_connection_t * | , | |||
pn_transport_t * | ||||
) |
Set connection and transport to the provided values, or create a new pn_connection_t or pn_transport_t if either is NULL.
The provided values belong to the connection driver and will be freed by pn_connection_driver_destroy().
The transport is bound automatically after the PN_CONNECTION_INIT has been is handled by the application. It can be bound earlier with pn_connection_driver_bind().
The following functions must be called before the transport is bound to have effect: pn_connection_set_username(), pn_connection_set_password(), pn_transport_set_server().
int pn_connection_driver_bind | ( | pn_connection_driver_t * | d | ) |
Force binding of the transport.
This happens automatically after the PN_CONNECTION_INIT is processed.
void pn_connection_driver_destroy | ( | pn_connection_driver_t * | ) |
Unbind, release and free the connection and transport.
Set all pointers to NULL. Does not free the pn_connection_driver_t struct itself.
pn_connection_t* pn_connection_driver_release_connection | ( | pn_connection_driver_t * | d | ) |
Disassociate the driver's connection from its transport and collector and sets d->connection = NULL.
Returns the previous value, which must be freed by the caller.
The transport and collector are still owned by the driver and will be freed by pn_connection_driver_destroy().
pn_rwbytes_t pn_connection_driver_read_buffer | ( | pn_connection_driver_t * | ) |
Get the read buffer.
Copy data from your input byte source to buf.start, up to buf.size. Call pn_connection_driver_read_done() when reading is complete.
buf.size==0 means reading is not possible: no buffer space or the read side is closed.
void pn_connection_driver_read_close | ( | pn_connection_driver_t * | ) |
Close the read side.
Call when the IO can no longer be read.
pn_bytes_t pn_connection_driver_write_buffer | ( | pn_connection_driver_t * | ) |
Get the write buffer.
Write data from buf.start to your IO destination, up to a max of buf.size. Call pn_connection_driver_write_done() when writing is complete.
buf.size==0 means there is nothing to write.
void pn_connection_driver_write_done | ( | pn_connection_driver_t * | , | |
size_t | n | |||
) |
Call when the first n bytes of pn_connection_driver_write_buffer() have been written to IO.
Reclaims the buffer space and reset the write buffer.
void pn_connection_driver_write_close | ( | pn_connection_driver_t * | ) |
Close the write side.
Call when IO can no longer be written to.
pn_event_t* pn_connection_driver_next_event | ( | pn_connection_driver_t * | ) |
Get the next event to handle.
bool pn_connection_driver_finished | ( | pn_connection_driver_t * | ) |
Return true if the the driver is closed for reading and writing and there are no more events.
Call pn_connection_driver_free() to free all related memory.
void pn_connection_driver_errorf | ( | pn_connection_driver_t * | d, | |
const char * | name, | |||
const char * | fmt, | |||
... | ||||
) |
Set transport error.
The name and formatted description are set on the transport condition, and returned as a PN_TRANSPORT_ERROR event from pn_connection_driver_next_event().
You must call this *before* pn_connection_driver_read_close() or pn_connection_driver_write_close() to ensure the error is processed.