A network channel supporting an AMQP connection. More...
Macros | |
#define | PN_TRACE_OFF |
Turn logging off entirely. | |
#define | PN_TRACE_RAW |
Log raw binary data going in and out of the transport. | |
#define | PN_TRACE_FRM |
Log protocol frames going in and out of the transport. | |
#define | PN_TRACE_DRV |
Log driver-related events. More... | |
#define | PN_TRACE_EVT |
Log events. | |
Typedefs | |
typedef int | pn_trace_t |
Holds the trace flags for an AMQP transport. More... | |
typedef void(* | pn_tracer_t) (pn_transport_t *transport, const char *message) |
Callback for customizing logging behaviour. | |
typedef struct pn_transport_t | pn_transport_t |
A network channel supporting an AMQP connection. More... | |
Functions | |
pn_transport_t * | pn_transport (void) |
Factory for creating a transport. More... | |
void | pn_transport_set_server (pn_transport_t *transport) |
Configure a transport as a server. More... | |
void | pn_transport_free (pn_transport_t *transport) |
Free a transport object. More... | |
const char * | pn_transport_get_user (pn_transport_t *transport) |
Retrieve the authenticated user. More... | |
void | pn_transport_require_auth (pn_transport_t *transport, bool required) |
Set whether a non-authenticated transport connection is allowed. More... | |
bool | pn_transport_is_authenticated (pn_transport_t *transport) |
Tell whether the transport connection is authenticated. More... | |
void | pn_transport_require_encryption (pn_transport_t *transport, bool required) |
Set whether a non encrypted transport connection is allowed. More... | |
bool | pn_transport_is_encrypted (pn_transport_t *transport) |
Tell whether the transport connection is encrypted. More... | |
pn_condition_t * | pn_transport_condition (pn_transport_t *transport) |
Get additional information about the condition of the transport. More... | |
pn_logger_t * | pn_transport_logger (pn_transport_t *transport) |
Get the transport logger. More... | |
pn_error_t * | pn_transport_error (pn_transport_t *transport) |
Deprecated - Use pn_transport_condition(). | |
int | pn_transport_bind (pn_transport_t *transport, pn_connection_t *connection) |
Deprecated - Use pn_connection_driver_init(). More... | |
int | pn_transport_unbind (pn_transport_t *transport) |
Deprecated - Use pn_connection_driver_destroy(). More... | |
void | pn_transport_trace (pn_transport_t *transport, pn_trace_t trace) |
Update a transports trace flags. More... | |
void | pn_transport_set_tracer (pn_transport_t *transport, pn_tracer_t tracer) |
Set the tracing function used by a transport. More... | |
pn_tracer_t | pn_transport_get_tracer (pn_transport_t *transport) |
Get the tracing function used by a transport. More... | |
void * | pn_transport_get_context (pn_transport_t *transport) |
Get the application context that is associated with a transport object. More... | |
void | pn_transport_set_context (pn_transport_t *transport, void *context) |
Set a new application context for a transport object. More... | |
pn_record_t * | pn_transport_attachments (pn_transport_t *transport) |
Get the attachments that are associated with a transport object. More... | |
void | pn_transport_log (pn_transport_t *transport, const char *message) |
Log a message using a transport's logging mechanism. More... | |
void | pn_transport_vlogf (pn_transport_t *transport, const char *fmt, va_list ap) |
Log a printf formatted message using a transport's logging mechanism. More... | |
void | pn_transport_logf (pn_transport_t *transport, const char *fmt,...) |
Log a printf formatted message using a transport's logging mechanism. More... | |
uint16_t | pn_transport_get_channel_max (pn_transport_t *transport) |
Get the maximum allowed channel for a transport. More... | |
int | pn_transport_set_channel_max (pn_transport_t *transport, uint16_t channel_max) |
Set the maximum allowed channel number for a transport. More... | |
uint16_t | pn_transport_remote_channel_max (pn_transport_t *transport) |
Get the maximum allowed channel of a transport's remote peer. More... | |
uint32_t | pn_transport_get_max_frame (pn_transport_t *transport) |
Get the maximum frame size of a transport. More... | |
void | pn_transport_set_max_frame (pn_transport_t *transport, uint32_t size) |
Set the maximum frame size of a transport. More... | |
uint32_t | pn_transport_get_remote_max_frame (pn_transport_t *transport) |
Get the maximum frame size of a transport's remote peer. More... | |
pn_millis_t | pn_transport_get_idle_timeout (pn_transport_t *transport) |
Get the idle timeout for a transport. More... | |
void | pn_transport_set_idle_timeout (pn_transport_t *transport, pn_millis_t timeout) |
Set the idle timeout for a transport. More... | |
pn_millis_t | pn_transport_get_remote_idle_timeout (pn_transport_t *transport) |
Get the idle timeout for a transport's remote peer. More... | |
ssize_t | pn_transport_input (pn_transport_t *transport, const char *bytes, size_t available) |
Deprecated - Use the Connection driver API. | |
ssize_t | pn_transport_output (pn_transport_t *transport, char *bytes, size_t size) |
Deprecated - Use the Connection driver API. | |
ssize_t | pn_transport_capacity (pn_transport_t *transport) |
Deprecated - Use the Connection driver API. More... | |
char * | pn_transport_tail (pn_transport_t *transport) |
Deprecated - Use the Connection driver API. More... | |
ssize_t | pn_transport_push (pn_transport_t *transport, const char *src, size_t size) |
Deprecated - Use the Connection driver API. More... | |
int | pn_transport_process (pn_transport_t *transport, size_t size) |
Deprecated - Use the Connection driver API. More... | |
int | pn_transport_close_tail (pn_transport_t *transport) |
Deprecated - Use the Connection driver API. More... | |
ssize_t | pn_transport_pending (pn_transport_t *transport) |
Deprecated - Use the Connection driver API. More... | |
const char * | pn_transport_head (pn_transport_t *transport) |
Deprecated - Use the Connection driver API. More... | |
ssize_t | pn_transport_peek (pn_transport_t *transport, char *dst, size_t size) |
Deprecated - Use the Connection driver API. More... | |
void | pn_transport_pop (pn_transport_t *transport, size_t size) |
Deprecated - Use the Connection driver API. More... | |
int | pn_transport_close_head (pn_transport_t *transport) |
Deprecated - Use the Connection driver API. More... | |
bool | pn_transport_quiesced (pn_transport_t *transport) |
Deprecated - Use the Connection driver API. More... | |
bool | pn_transport_head_closed (pn_transport_t *transport) |
Deprecated - Use the Connection driver API. More... | |
bool | pn_transport_tail_closed (pn_transport_t *transport) |
Deprecated - Use the Connection driver API. More... | |
bool | pn_transport_closed (pn_transport_t *transport) |
Deprecated - Use the Connection driver API. More... | |
int64_t | pn_transport_tick (pn_transport_t *transport, int64_t now) |
Process any pending transport timer events. More... | |
uint64_t | pn_transport_get_frames_output (const pn_transport_t *transport) |
Deprecated - No replacement. More... | |
uint64_t | pn_transport_get_frames_input (const pn_transport_t *transport) |
Deprecated - No replacement. More... | |
pn_connection_t * | pn_transport_connection (pn_transport_t *transport) |
Access the AMQP Connection associated with the transport. More... | |
A network channel supporting an AMQP connection.
#define PN_TRACE_DRV |
Log driver-related events.
For example, initialization, end of stream, and so on.
typedef int pn_trace_t |
Holds the trace flags for an AMQP transport.
The trace flags for an AMQP transport control what sort of information is logged by an AMQP transport. The following bits can be set:
typedef struct pn_transport_t pn_transport_t |
A network channel supporting an AMQP connection.
A pn_transport_t encapsulates the transport related state of all AMQP endpoint objects associated with a physical network connection at a given point in time.
pn_transport_t* pn_transport | ( | void | ) |
Factory for creating a transport.
A transport is used by a connection to interface with the network. There can only be one connection associated with a transport.
Initially a transport is configured to be a client transport. Use pn_transport_set_server() to configure the transport as a server transport.
A client transport initiates outgoing connections.
A client transport must be configured with the protocol layers to use and cannot configure itself automatically.
A server transport accepts incoming connections. It can automatically configure itself to include the various protocol layers depending on the incoming protocol headers.
void pn_transport_set_server | ( | pn_transport_t * | transport | ) |
void pn_transport_free | ( | pn_transport_t * | transport | ) |
Free a transport object.
When a transport is freed, it is automatically unbound from its associated connection.
[in] | transport | a transport object or NULL |
const char* pn_transport_get_user | ( | pn_transport_t * | transport | ) |
Retrieve the authenticated user.
This is usually used at the the server end to find the name of the authenticated user. On the client it will merely return whatever user was passed in to the pn_connection_set_user() API of the bound connection.
The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received.
[in] | transport | the transport |
void pn_transport_require_auth | ( | pn_transport_t * | transport, |
bool | required | ||
) |
Set whether a non-authenticated transport connection is allowed.
There are several ways within the AMQP protocol suite to get unauthenticated connections:
The default if this option is not set is to allow unauthenticated connections.
[in] | transport | the transport |
[in] | required | boolean is true when authenticated connections are required |
bool pn_transport_is_authenticated | ( | pn_transport_t * | transport | ) |
Tell whether the transport connection is authenticated.
Note that this property may not be stable until the PN_CONNECTION_REMOTE_OPEN event is received.
[in] | transport | the transport |
void pn_transport_require_encryption | ( | pn_transport_t * | transport, |
bool | required | ||
) |
Set whether a non encrypted transport connection is allowed.
There are several ways within the AMQP protocol suite to get encrypted connections:
The default if this option is not set is to allow unencrypted connections.
[in] | transport | the transport |
[in] | required | boolean is true when encrypted connections are required |
bool pn_transport_is_encrypted | ( | pn_transport_t * | transport | ) |
Tell whether the transport connection is encrypted.
Note that this property may not be stable until the PN_CONNECTION_REMOTE_OPEN event is received.
[in] | transport | the transport |
pn_condition_t* pn_transport_condition | ( | pn_transport_t * | transport | ) |
Get additional information about the condition of the transport.
When a PN_TRANSPORT_ERROR event occurs, this operation can be used to access the details of the error condition.
The pointer returned by this operation is valid until the transport object is freed.
[in] | transport | the transport object |
pn_logger_t* pn_transport_logger | ( | pn_transport_t * | transport | ) |
Get the transport logger.
This can be used to control the logging information emitted by the transport
The pointer returned by this operation is valid until the transport object is freed.
[in] | transport | the transport object |
int pn_transport_bind | ( | pn_transport_t * | transport, |
pn_connection_t * | connection | ||
) |
Deprecated - Use pn_connection_driver_init().
Binds the transport to an AMQP connection.
int pn_transport_unbind | ( | pn_transport_t * | transport | ) |
Deprecated - Use pn_connection_driver_destroy().
Unbinds a transport from its AMQP connection.
void pn_transport_trace | ( | pn_transport_t * | transport, |
pn_trace_t | trace | ||
) |
Update a transports trace flags.
The trace flags for a transport control what sort of information is logged. See pn_trace_t for more details.
[in] | transport | a transport object |
[in] | trace | the trace flags |
void pn_transport_set_tracer | ( | pn_transport_t * | transport, |
pn_tracer_t | tracer | ||
) |
Set the tracing function used by a transport.
The tracing function is called to perform logging. Overriding this function allows embedding applications to divert the engine's logging to a place of their choice.
[in] | transport | a transport object |
[in] | tracer | the tracing function |
pn_tracer_t pn_transport_get_tracer | ( | pn_transport_t * | transport | ) |
Get the tracing function used by a transport.
[in] | transport | a transport object |
void* pn_transport_get_context | ( | pn_transport_t * | transport | ) |
Get the application context that is associated with a transport object.
The application context for a transport may be set using pn_transport_set_context.
[in] | transport | the transport whose context is to be returned. |
void pn_transport_set_context | ( | pn_transport_t * | transport, |
void * | context | ||
) |
Set a new application context for a transport object.
The application context for a transport object may be retrieved using pn_transport_get_context.
[in] | transport | the transport object |
[in] | context | the application context |
pn_record_t* pn_transport_attachments | ( | pn_transport_t * | transport | ) |
Get the attachments that are associated with a transport object.
[in] | transport | the transport whose attachments are to be returned. |
void pn_transport_log | ( | pn_transport_t * | transport, |
const char * | message | ||
) |
Log a message using a transport's logging mechanism.
This can be useful in a debugging context as the log message will be prefixed with the transport's identifier.
[in] | transport | a transport object |
[in] | message | the message to be logged |
void pn_transport_vlogf | ( | pn_transport_t * | transport, |
const char * | fmt, | ||
va_list | ap | ||
) |
Log a printf formatted message using a transport's logging mechanism.
This can be useful in a debugging context as the log message will be prefixed with the transport's identifier.
[in] | transport | a transport object |
[in] | fmt | the printf formatted message to be logged |
[in] | ap | a vector containing the format arguments |
void pn_transport_logf | ( | pn_transport_t * | transport, |
const char * | fmt, | ||
... | |||
) |
Log a printf formatted message using a transport's logging mechanism.
This can be useful in a debugging context as the log message will be prefixed with the transport's identifier.
[in] | transport | a transport object |
[in] | fmt | the printf formatted message to be logged |
uint16_t pn_transport_get_channel_max | ( | pn_transport_t * | transport | ) |
Get the maximum allowed channel for a transport.
This will be the minimum of
[in] | transport | a transport object |
int pn_transport_set_channel_max | ( | pn_transport_t * | transport, |
uint16_t | channel_max | ||
) |
Set the maximum allowed channel number for a transport.
Note that this is the maximum channel number allowed, giving a valid channel number range of [0..channel_max]. Therefore the maximum number of simultaneously active channels will be channel_max plus 1. You can call this function more than once to raise and lower the limit your application imposes on max channels for this transport. However, smaller limits may be imposed by this library, or by the remote peer. After the OPEN frame has been sent to the remote peer, further calls to this function will have no effect.
[in] | transport | a transport object |
[in] | channel_max | the maximum allowed channel |
uint16_t pn_transport_remote_channel_max | ( | pn_transport_t * | transport | ) |
Get the maximum allowed channel of a transport's remote peer.
[in] | transport | a transport object |
uint32_t pn_transport_get_max_frame | ( | pn_transport_t * | transport | ) |
Get the maximum frame size of a transport.
[in] | transport | a transport object |
void pn_transport_set_max_frame | ( | pn_transport_t * | transport, |
uint32_t | size | ||
) |
Set the maximum frame size of a transport.
[in] | transport | a transport object |
[in] | size | the maximum frame size for the transport object |
uint32_t pn_transport_get_remote_max_frame | ( | pn_transport_t * | transport | ) |
Get the maximum frame size of a transport's remote peer.
[in] | transport | a transport object |
pn_millis_t pn_transport_get_idle_timeout | ( | pn_transport_t * | transport | ) |
Get the idle timeout for a transport.
A zero idle timeout means heartbeats are disabled.
[in] | transport | a transport object |
void pn_transport_set_idle_timeout | ( | pn_transport_t * | transport, |
pn_millis_t | timeout | ||
) |
Set the idle timeout for a transport.
A zero idle timeout means heartbeats are disabled.
[in] | transport | a transport object |
[in] | timeout | the idle timeout for the transport object |
pn_millis_t pn_transport_get_remote_idle_timeout | ( | pn_transport_t * | transport | ) |
Get the idle timeout for a transport's remote peer.
A zero idle timeout means heartbeats are disabled.
[in] | transport | a transport object |
ssize_t pn_transport_capacity | ( | pn_transport_t * | transport | ) |
Deprecated - Use the Connection driver API.
Get the amount of free space for input following the transport's tail pointer.
If the engine is in an exceptional state such as encountering an error condition or reaching the end of stream state, a negative value will be returned indicating the condition. If an error is indicated, further details can be obtained from pn_transport_condition(). Calls to pn_transport_process() may alter the value of this pointer. See pn_transport_process for details.
[in] | transport | the transport |
char* pn_transport_tail | ( | pn_transport_t * | transport | ) |
Deprecated - Use the Connection driver API.
Get the transport's tail pointer.
The amount of free space following this pointer is reported by pn_transport_capacity. Calls to pn_transport_process may alter the value of this pointer. See pn_transport_process for details.
[in] | transport | the transport |
ssize_t pn_transport_push | ( | pn_transport_t * | transport, |
const char * | src, | ||
size_t | size | ||
) |
Deprecated - Use the Connection driver API.
Pushes the supplied bytes into the tail of the transport.
This is equivalent to copying size
bytes after the tail pointer and then calling pn_transport_process with an argument of size
. Only some of the bytes will be copied if there is insufficient capacity available. Use pn_transport_capacity to determine how much capacity the transport has.
[in] | transport | the transport |
[in] | src | the start of the data to push into the transport |
[in] | size | the amount of data to push into the transport |
int pn_transport_process | ( | pn_transport_t * | transport, |
size_t | size | ||
) |
Deprecated - Use the Connection driver API.
Process input data following the tail pointer.
Calling this function will cause the transport to consume size
bytes of input occupying the free space following the tail pointer. Calls to this function may change the value of pn_transport_tail, as well as the amount of free space reported by pn_transport_capacity.
[in] | transport | the transport |
[in] | size | the amount of data written to the transport's input buffer |
int pn_transport_close_tail | ( | pn_transport_t * | transport | ) |
Deprecated - Use the Connection driver API.
Indicate that the input has reached End Of Stream (EOS).
This tells the transport that no more input will be forthcoming.
[in] | transport | the transport |
ssize_t pn_transport_pending | ( | pn_transport_t * | transport | ) |
Deprecated - Use the Connection driver API.
Get the number of pending output bytes following the transport's head pointer.
If the engine is in an exceptional state such as encountering an error condition or reaching the end of stream state, a negative value will be returned indicating the condition. If an error is indicated, further details can be obtained from pn_transport_condition(). Calls to pn_transport_pop() may alter the value of this pointer. See pn_transport_pop() for details.
[in] | transport | the transport |
const char* pn_transport_head | ( | pn_transport_t * | transport | ) |
Deprecated - Use the Connection driver API.
Get the transport's head pointer.
This pointer references queued output data. The pn_transport_pending function reports how many bytes of output data follow this pointer. Calls to pn_transport_pop may alter this pointer and any data it references. See pn_transport_pop for details.
[in] | transport | the transport |
ssize_t pn_transport_peek | ( | pn_transport_t * | transport, |
char * | dst, | ||
size_t | size | ||
) |
Deprecated - Use the Connection driver API.
Copies size
bytes from the head of the transport to the dst
pointer.
It is an error to call this with a value of size
that is greater than the value reported by pn_transport_pending.
[in] | transport | the transport |
[out] | dst | the destination buffer |
[in] | size | the capacity of the destination buffer |
void pn_transport_pop | ( | pn_transport_t * | transport, |
size_t | size | ||
) |
Deprecated - Use the Connection driver API.
Removes size
bytes of output from the pending output queue following the transport's head pointer.
Calls to this function may alter the transport's head pointer as well as the number of pending bytes reported by pn_transport_pending.
[in] | transport | the transport |
[in] | size | the number of bytes to remove |
int pn_transport_close_head | ( | pn_transport_t * | transport | ) |
Deprecated - Use the Connection driver API.
Indicate that the output has closed.
This tells the transport that no more output will be popped.
[in] | transport | the transport |
bool pn_transport_quiesced | ( | pn_transport_t * | transport | ) |
Deprecated - Use the Connection driver API.
Check if a transport has buffered data.
[in] | transport | a transport object |
bool pn_transport_head_closed | ( | pn_transport_t * | transport | ) |
Deprecated - Use the Connection driver API.
True if pn_transport_close_head() has been called.
bool pn_transport_tail_closed | ( | pn_transport_t * | transport | ) |
Deprecated - Use the Connection driver API.
True if pn_transport_close_tail() has been called.
bool pn_transport_closed | ( | pn_transport_t * | transport | ) |
Deprecated - Use the Connection driver API.
Equivalent to pn_transport_head_closed(transport) && pn_transport_tail_closed(transport)
int64_t pn_transport_tick | ( | pn_transport_t * | transport, |
int64_t | now | ||
) |
Process any pending transport timer events.
This method should be called after all pending input has been processed by the transport and before generating output. It returns the deadline for the next pending timer event, if any are present.
Note that this function does nothing until the first data is read from or written to the transport.
[in] | transport | the transport to process. |
[in] | now | A monotonically-increasing time value in milliseconds. Does not need to be wall-clock time or a valid AMQP timestamp, but must increase monotonically. |
uint64_t pn_transport_get_frames_output | ( | const pn_transport_t * | transport | ) |
Deprecated - No replacement.
Get the number of frames output by a transport.
[in] | transport | a transport object |
uint64_t pn_transport_get_frames_input | ( | const pn_transport_t * | transport | ) |
Deprecated - No replacement.
Get the number of frames input by a transport.
[in] | transport | a transport object |
pn_connection_t* pn_transport_connection | ( | pn_transport_t * | transport | ) |
Access the AMQP Connection associated with the transport.
[in] | transport | a transport object |