Qpid Proton C API  0.17.0
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
connection_driver.h File Reference

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.


struct  pn_connection_driver_t
 The elements needed to drive AMQP IO and events. More...


typedef struct
 The elements needed to drive AMQP IO and events.


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_tpn_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_tpn_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.

Detailed Description

Experimental - Low-level IO integration

Associate a Connection and Transport with AMQP byte streams from any source.

  • process AMQP-encoded bytes from some input byte stream
  • generate pn_event_t events for your application to handle
  • encode resulting AMQP output bytes for some output byte stream

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 set 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 forms an independent unit. Different connections can be processed concurrently by different threads.