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

Functions

PN_EXTERN pn_buf_t pn_buf (char *data, size_t size)
 Create a pn_buf.
PN_EXTERN pn_cbuf_t pn_cbuf (const char *data, size_t size)
 Create a pn_cbuf.
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.
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.
PN_EXTERN pn_buf_t pn_connection_engine_read_buffer (pn_connection_engine_t *)
 The engine's read buffer.
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_EXTERN void pn_connection_engine_read_close (pn_connection_engine_t *)
 Close the read side of the transport when no more data is available.
PN_EXTERN pn_cbuf_t pn_connection_engine_write_buffer (pn_connection_engine_t *)
 The engine's write buffer.
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.
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.
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().
PN_EXTERN pn_event_tpn_connection_engine_dispatch (pn_connection_engine_t *)
 Get the next available event.
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_EXTERN pn_connection_tpn_connection_engine_connection (pn_connection_engine_t *)
 Get the AMQP connection, owned by the pn_connection_engine_t.
PN_EXTERN pn_transport_tpn_connection_engine_transport (pn_connection_engine_t *)
 Get the proton transport, owned by the pn_connection_engine_t.
PN_EXTERN pn_condition_tpn_connection_engine_condition (pn_connection_engine_t *)
 Get the condition object for the engine's transport.

Function Documentation

PN_EXTERN pn_buf_t pn_buf ( char *  data,
size_t  size 
)

Create a pn_buf.

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

Create a pn_cbuf.

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_EXTERN pn_connection_t* pn_connection_engine_connection ( pn_connection_engine_t  ) 

Get the AMQP connection, owned by the pn_connection_engine_t.

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_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_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_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_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_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_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_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_EXTERN pn_transport_t* pn_connection_engine_transport ( pn_connection_engine_t  ) 

Get the proton transport, owned by the pn_connection_engine_t.

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

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines

Generated on 23 Sep 2016 for proton by  doxygen 1.6.1