Qpid Proton C API
0.16.0
|
Experimental - Low-level IO integration More...
#include <proton/import_export.h>
#include <proton/event.h>
#include <proton/types.h>
#include <stdarg.h>
Go to the source code of this file.
Classes | |
struct | pn_connection_driver_t |
The elements needed to drive AMQP IO and events. More... | |
Typedefs | |
typedef struct pn_connection_driver_t | pn_connection_driver_t |
The elements needed to drive AMQP IO and events. | |
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. More... | |
int | pn_connection_driver_bind (pn_connection_driver_t *d) |
Force binding of the transport. More... | |
void | pn_connection_driver_destroy (pn_connection_driver_t *) |
Unbind, release and free the connection and transport. More... | |
pn_rwbytes_t | pn_connection_driver_read_buffer (pn_connection_driver_t *) |
Get the read buffer. More... | |
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. More... | |
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. More... | |
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. More... | |
void | pn_connection_driver_write_close (pn_connection_driver_t *) |
Close the write side. More... | |
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 side. | |
pn_event_t * | pn_connection_driver_next_event (pn_connection_driver_t *) |
Get the next event to handle. More... | |
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. More... | |
void | pn_connection_driver_errorf (pn_connection_driver_t *d, const char *name, const char *fmt,...) |
Set IO error information. More... | |
void | pn_connection_driver_verrorf (pn_connection_driver_t *d, const char *name, const char *fmt, va_list) |
Set IO error information via a va_list, see pn_connection_driver_errorf() | |
void | pn_connection_driver_log (pn_connection_driver_t *d, const char *msg) |
Log a string message using the connection's transport log. | |
void | pn_connection_driver_logf (pn_connection_driver_t *d, char *fmt,...) |
Log a printf formatted message using the connection's transport log. | |
void | pn_connection_driver_vlogf (pn_connection_driver_t *d, const char *fmt, va_list ap) |
Log a printf formatted message using the connection's transport log. | |
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. | |
Experimental - 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.
The pn_connection_driver_*() functions do not return an error code. IO errors set the transport condition and are returned as a PN_TRANSPORT_ERROR. The integration code can set errors using pn_connection_driver_errorf().
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.
The Connection driver types are not thread safe, but each connection and its associated types forms an independent unit. Different connections can be processed concurrently by different threads.