Connection driver
IO

Unsettled API - An API for low-level IO integration. More...

Collaboration diagram for Connection driver:

## Classes

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

## Macros

#define | PN_TRANSPORT_WRITE_CLOSED
| The write side of the transport is closed, it will no longer produce bytes to write to external IO. More...
#define | PN_TRANSPORT_READ_CLOSED
| The read side of the transport is closed, it will no longer read bytes from external IO. 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_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. 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.
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 transport error. More...
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().
pn_connection_driver_t ** | pn_connection_driver_ptr (pn_connection_t *connection)
| Associate a pn_connection_t with its pn_connection_driver_t. More...

## Detailed Description

Unsettled API - An API for 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 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.

## Class Documentation

## pn_connection_driver_t

struct pn_connection_driver_t

The elements needed to drive AMQP IO and events.

Class Members
pn_connection_t * | connection |
pn_transport_t * | transport |
pn_collector_t * | collector |
pn_event_batch_t | batch |

## Macro Definition Documentation

## PN_TRANSPORT_WRITE_CLOSED

#define PN_TRANSPORT_WRITE_CLOSED

The write side of the transport is closed, it will no longer produce bytes to write to external IO.

Synonym for PN_TRANSPORT_HEAD_CLOSED

## PN_TRANSPORT_READ_CLOSED

#define PN_TRANSPORT_READ_CLOSED

The read side of the transport is closed, it will no longer read bytes from external IO.

Alias for PN_TRANSPORT_TAIL_CLOSED

## Function Documentation

## pn_connection_driver_init()

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().

Returns
  PN_OUT_OF_MEMORY if any allocation fails.

## pn_connection_driver_bind()

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.

Returns
  PN_STATE_ERR if the transport is already bound.

## pn_connection_driver_destroy()

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_driver_release_connection()

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().

Note
  This has nothing to do with pn_connection_release()

## pn_connection_driver_read_buffer()

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.

## pn_connection_driver_read_close()

void pn_connection_driver_read_close | ( | pn_connection_driver_t * |  | ) |

Close the read side.

Call when the IO can no longer be read.

## pn_connection_driver_write_buffer()

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.

## pn_connection_driver_write_done()

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.

## pn_connection_driver_write_close()

void pn_connection_driver_write_close | ( | pn_connection_driver_t * |  | ) |

Close the write side.

Call when IO can no longer be written to.

## pn_connection_driver_next_event()

pn_event_t* pn_connection_driver_next_event | ( | pn_connection_driver_t * |  | ) |

Get the next event to handle.

Returns
  pointer is valid till the next call of pn_connection_driver_next(). NULL if there are no more events available now, reading/writing may produce more.

## pn_connection_driver_finished()

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.

## pn_connection_driver_errorf()

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.

## pn_connection_driver_ptr()

pn_connection_driver_t** pn_connection_driver_ptr | ( | pn_connection_t * | connection | ) |

Associate a pn_connection_t with its pn_connection_driver_t.

NOTE: this is only for use by IO integration writers. If you are using the standard pn_proactor_t you must not use this function.

Returns
  pointer to the pn_connection_driver_t* field in a pn_connection_t.

Return type is pointer to a pointer so that the caller can (if desired) use atomic operations when loading and storing the value.