Connection driver

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

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

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_sized (pn_connection_driver_t *, size_t n)
	Try to get a read buffer with the specified size. 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...
pn_bytes_t	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()
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

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

pn_rwbytes_t pn_connection_driver_read_buffer_sized	(	pn_connection_driver_t *	,
		size_t	n
	)

Try to get a read buffer with the specified size.

This will try to grow the read buffer to the specified size and then it will return whatever size read buffer can be got.

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

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