The Connection Engine

## Data Structures

struct | pn_buf_t
| A modifiable memory buffer. More...
struct | pn_cbuf_t
| A read-only memory buffer. More...
struct | pn_connection_engine_t
| A connection engine is a trio of pn_connection_t, pn_transport_t and pn_collector_t. More...

## Typedefs

typedef struct pn_buf_t | pn_buf_t
| A modifiable memory buffer. More...
typedef struct pn_cbuf_t | pn_cbuf_t
| A read-only memory buffer. More...
typedef struct pn_connection_engine_t | pn_connection_engine_t
| A connection engine is a trio of pn_connection_t, pn_transport_t and pn_collector_t. More...

## Functions

PN_EXTERN pn_buf_t | pn_buf (char *data, size_t size)
| Create a pn_buf. More...
PN_EXTERN pn_cbuf_t | pn_cbuf (const char *data, size_t size)
| Create a pn_cbuf. More...
PN_EXTERN int | pn_connection_engine_init (pn_connection_engine_t *engine)
| Initialize a pn_connection_engine_t struct with a new connection, transport and collector. More...
PN_EXTERN void | pn_connection_engine_final (pn_connection_engine_t *engine)
| Release the connection, transport and collector associated with engine, set all the pointers to NULL. More...
PN_EXTERN pn_buf_t | pn_connection_engine_read_buffer (pn_connection_engine_t *)
| The engine's read buffer. More...
PN_EXTERN void | pn_connection_engine_read_done (pn_connection_engine_t *, size_t n)
| Consume the first n bytes of data in pn_connection_engine_read_buffer() and update the buffer. More...
PN_EXTERN void | pn_connection_engine_read_close (pn_connection_engine_t *)
| Close the read side of the transport when no more data is available. More...
PN_EXTERN pn_cbuf_t | pn_connection_engine_write_buffer (pn_connection_engine_t *)
| The engine's write buffer. More...
PN_EXTERN void | pn_connection_engine_write_done (pn_connection_engine_t *, size_t n)
| Call when the first n bytes of pn_connection_engine_write_buffer() have been written to IO and can be re-used for new data. More...
PN_EXTERN void | pn_connection_engine_write_close (pn_connection_engine_t *)
| Call when the write side of IO has closed and no more data can be written. More...
PN_EXTERN void | pn_connection_engine_disconnected (pn_connection_engine_t *)
| Close both sides of the transport, equivalent to pn_connection_engine_read_close(); pn_connection_engine_write_close() More...
PN_EXTERN pn_event_t * | pn_connection_engine_dispatch (pn_connection_engine_t *)
| Get the next available event. More...
PN_EXTERN bool | pn_connection_engine_finished (pn_connection_engine_t *)
| Return true if the engine is finished - all data has been written, all events have been handled and the transport is closed. More...
PN_EXTERN pn_connection_t * | pn_connection_engine_connection (pn_connection_engine_t *)
| Get the AMQP connection, owned by the pn_connection_engine_t. More...
PN_EXTERN pn_transport_t * | pn_connection_engine_transport (pn_connection_engine_t *)
| Get the proton transport, owned by the pn_connection_engine_t. More...
PN_EXTERN pn_condition_t * | pn_connection_engine_condition (pn_connection_engine_t *)
| Get the condition object for the engine's transport. More...

## Detailed Description

## Typedef Documentation

## pn_buf_t

typedef struct pn_buf_t pn_buf_t

A modifiable memory buffer.

## pn_cbuf_t

typedef struct pn_cbuf_t pn_cbuf_t

A read-only memory buffer.

## pn_connection_engine_t

typedef struct pn_connection_engine_t pn_connection_engine_t

A connection engine is a trio of pn_connection_t, pn_transport_t and pn_collector_t.

Use the pn_connection_engine_*() functions to operate on it. It is a plain struct, not a proton object. Use pn_connection_engine_init to set up the initial objects and pn_connection_engine_final to release them.

## Function Documentation

## pn_buf()

PN_EXTERN pn_buf_t pn_buf | ( | char * | data,
|  | size_t | size
| ) |  |

Create a pn_buf.

## pn_cbuf()

PN_EXTERN pn_cbuf_t pn_cbuf | ( | const char * | data,
|  | size_t | size
| ) |  |

Create a pn_cbuf.

## pn_connection_engine_condition()

PN_EXTERN pn_condition_t* pn_connection_engine_condition | ( | pn_connection_engine_t * |  | ) |

Get the condition object for the engine's transport.

Note that IO errors should be set on this, the transport condition, not on the pn_connection_t condition. The connection's condition is for errors received via the AMQP protocol, the transport condition is for errors in the the IO layer such as a socket read or disconnect errors.

## pn_connection_engine_connection()

PN_EXTERN pn_connection_t* pn_connection_engine_connection | ( | pn_connection_engine_t * |  | ) |

Get the AMQP connection, owned by the pn_connection_engine_t.

## pn_connection_engine_disconnected()

PN_EXTERN void pn_connection_engine_disconnected | ( | pn_connection_engine_t * |  | ) |

Close both sides of the transport, equivalent to pn_connection_engine_read_close(); pn_connection_engine_write_close()

You must still call pn_connection_engine_dispatch() to process final events.

To provide transport error information to the handler, set it on pn_connection_engine_condition() before calling pn_connection_engine_disconnected(). This sets the error on the pn_transport_t object.

Note this does not modify the pn_connection_t, so you can distinguish between a connection close error sent by the remote peer (which will set the connection condition) and a transport error (which sets the transport condition.)

## pn_connection_engine_dispatch()

PN_EXTERN pn_event_t* pn_connection_engine_dispatch | ( | pn_connection_engine_t * |  | ) |

Get the next available event.

Call in a loop until it returns NULL to dispatch all available events. Note this call may modify the read and write buffers.

Returns
  Pointer to the next event, or NULL if there are none available.

## pn_connection_engine_final()

PN_EXTERN void pn_connection_engine_final | ( | pn_connection_engine_t * | engine | ) |

Release the connection, transport and collector associated with engine, set all the pointers to NULL.

Only call on an engine that was initialized with pn_connection_engine_init

## pn_connection_engine_finished()

PN_EXTERN bool pn_connection_engine_finished | ( | pn_connection_engine_t * |  | ) |

Return true if the engine is finished - all data has been written, all events have been handled and the transport is closed.

## pn_connection_engine_init()

PN_EXTERN int pn_connection_engine_init | ( | pn_connection_engine_t * | engine | ) |

Initialize a pn_connection_engine_t struct with a new connection, transport and collector.

Return 0 on success, a proton error code on failure.

## pn_connection_engine_read_buffer()

PN_EXTERN pn_buf_t pn_connection_engine_read_buffer | ( | pn_connection_engine_t * |  | ) |

The engine's read buffer.

Read data from your IO source into buf.data, up to a max of buf.size. Then call pn_connection_engine_read_done().

buf.size==0 means the engine cannot read presently, calling pn_connection_engine_dispatch() may create more buffer space.

## pn_connection_engine_read_close()

PN_EXTERN void pn_connection_engine_read_close | ( | pn_connection_engine_t * |  | ) |

Close the read side of the transport when no more data is available.

Note there may still be events for pn_connection_engine_dispatch() or data in pn_connection_engine_write_buffer()

## pn_connection_engine_read_done()

PN_EXTERN void pn_connection_engine_read_done | ( | pn_connection_engine_t * | ,
|  | size_t | n
| ) |  |

Consume the first n bytes of data in pn_connection_engine_read_buffer() and update the buffer.

## pn_connection_engine_transport()

PN_EXTERN pn_transport_t* pn_connection_engine_transport | ( | pn_connection_engine_t * |  | ) |

Get the proton transport, owned by the pn_connection_engine_t.

## pn_connection_engine_write_buffer()

PN_EXTERN pn_cbuf_t pn_connection_engine_write_buffer | ( | pn_connection_engine_t * |  | ) |

The engine's write buffer.

Write data from buf.data to your IO destination, up to a max of buf.size. Then call pn_connection_engine_write_done().

buf.size==0 means the engine has nothing to write presently. Calling pn_connection_engine_dispatch() may generate more data.

## pn_connection_engine_write_close()

PN_EXTERN void pn_connection_engine_write_close | ( | pn_connection_engine_t * |  | ) |

Call when the write side of IO has closed and no more data can be written.

Note that there may still be events for pn_connection_engine_dispatch() or data to read into pn_connection_engine_read_buffer().

## pn_connection_engine_write_done()

PN_EXTERN void pn_connection_engine_write_done | ( | pn_connection_engine_t * | ,
|  | size_t | n
| ) |  |

Call when the first n bytes of pn_connection_engine_write_buffer() have been written to IO and can be re-used for new data.

Updates the buffer.