Qpid Proton C API  0.29.0
Transport

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_tpn_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_tpn_transport_condition (pn_transport_t *transport)
 Get additional information about the condition of the transport. More...
 
pn_error_tpn_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_tpn_transport_connection (pn_transport_t *transport)
 Access the AMQP Connection associated with the transport. More...
 

Detailed Description

A network channel supporting an AMQP connection.

Macro Definition Documentation

◆ PN_TRACE_DRV

#define PN_TRACE_DRV

Log driver-related events.

For example, initialization, end of stream, and so on.

Typedef Documentation

◆ pn_trace_t

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:

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

Function Documentation

◆ pn_transport()

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.

Returns
pointer to new transport
Examples:
broker.c.

◆ pn_transport_set_server()

void pn_transport_set_server ( pn_transport_t transport)

Configure a transport as a server.

Parameters
[in]transporta transport object
Examples:
broker.c.

◆ pn_transport_free()

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.

Parameters
[in]transporta transport object or NULL

◆ pn_transport_get_user()

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.

Parameters
[in]transportthe transport
Returns
If a the user is anonymous (either no SASL layer is negotiated or the SASL ANONYMOUS mechanism is used) then the user will be "anonymous" Otherwise a string containing the user is returned.

◆ pn_transport_require_auth()

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:

  • Use no SASL layer (with either no TLS or TLS without client certificates)
  • Use a SASL layer but the ANONYMOUS mechanism

The default if this option is not set is to allow unauthenticated connections.

Parameters
[in]transportthe transport
[in]requiredboolean is true when authenticated connections are required
Examples:
direct.c.

◆ pn_transport_is_authenticated()

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.

Parameters
[in]transportthe transport
Returns
bool representing authentication

◆ pn_transport_require_encryption()

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:

  • Use TLS
  • Use a SASL with a mechanism that supports security layers

The default if this option is not set is to allow unencrypted connections.

Parameters
[in]transportthe transport
[in]requiredboolean is true when encrypted connections are required
Examples:
broker.c.

◆ pn_transport_is_encrypted()

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.

Parameters
[in]transportthe transport
Returns
bool representing encryption

◆ pn_transport_condition()

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.

Parameters
[in]transportthe transport object
Returns
the transport's condition object
Examples:
broker.c, direct.c, receive.c, and send.c.

◆ pn_transport_bind()

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.

Returns
an error code, or 0 on success

◆ pn_transport_unbind()

int pn_transport_unbind ( pn_transport_t transport)

Deprecated - Use pn_connection_driver_destroy().

Unbinds a transport from its AMQP connection.

Returns
an error code, or 0 on success

◆ pn_transport_trace()

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.

Parameters
[in]transporta transport object
[in]tracethe trace flags

◆ pn_transport_set_tracer()

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.

Parameters
[in]transporta transport object
[in]tracerthe tracing function

◆ pn_transport_get_tracer()

pn_tracer_t pn_transport_get_tracer ( pn_transport_t transport)

Get the tracing function used by a transport.

Parameters
[in]transporta transport object
Returns
the tracing function used by a transport

◆ pn_transport_get_context()

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.

Parameters
[in]transportthe transport whose context is to be returned.
Returns
the application context for the transport object

◆ pn_transport_set_context()

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.

Parameters
[in]transportthe transport object
[in]contextthe application context

◆ pn_transport_attachments()

pn_record_t* pn_transport_attachments ( pn_transport_t transport)

Get the attachments that are associated with a transport object.

Parameters
[in]transportthe transport whose attachments are to be returned.
Returns
the attachments for the transport object

◆ pn_transport_log()

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.

Parameters
[in]transporta transport object
[in]messagethe message to be logged

◆ pn_transport_vlogf()

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.

Parameters
[in]transporta transport object
[in]fmtthe printf formatted message to be logged
[in]apa vector containing the format arguments

◆ pn_transport_logf()

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.

Parameters
[in]transporta transport object
[in]fmtthe printf formatted message to be logged

◆ pn_transport_get_channel_max()

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

  1. limit imposed by this proton implementation
  2. limit imposed by remote peer
  3. limit imposed by this application, using pn_transport_set_channel_max()
Parameters
[in]transporta transport object
Returns
the maximum allowed channel

◆ pn_transport_set_channel_max()

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.

Parameters
[in]transporta transport object
[in]channel_maxthe maximum allowed channel
Returns
PN_OK, or PN_STATE_ERR if it is too late to change channel_max

◆ pn_transport_remote_channel_max()

uint16_t pn_transport_remote_channel_max ( pn_transport_t transport)

Get the maximum allowed channel of a transport's remote peer.

Parameters
[in]transporta transport object
Returns
the maximum allowed channel of the transport's remote peer

◆ pn_transport_get_max_frame()

uint32_t pn_transport_get_max_frame ( pn_transport_t transport)

Get the maximum frame size of a transport.

Parameters
[in]transporta transport object
Returns
the maximum frame size of the transport object

◆ pn_transport_set_max_frame()

void pn_transport_set_max_frame ( pn_transport_t transport,
uint32_t  size 
)

Set the maximum frame size of a transport.

Parameters
[in]transporta transport object
[in]sizethe maximum frame size for the transport object

◆ pn_transport_get_remote_max_frame()

uint32_t pn_transport_get_remote_max_frame ( pn_transport_t transport)

Get the maximum frame size of a transport's remote peer.

Parameters
[in]transporta transport object
Returns
the maximum frame size of the transport's remote peer

◆ pn_transport_get_idle_timeout()

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.

Parameters
[in]transporta transport object
Returns
the transport's idle timeout

◆ pn_transport_set_idle_timeout()

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.

Parameters
[in]transporta transport object
[in]timeoutthe idle timeout for the transport object

◆ pn_transport_get_remote_idle_timeout()

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.

Parameters
[in]transporta transport object
Returns
the idle timeout for the transport's remote peer

◆ pn_transport_capacity()

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.

Parameters
[in]transportthe transport
Returns
the free space in the transport, PN_EOS or error code if < 0

◆ pn_transport_tail()

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.

Parameters
[in]transportthe transport
Returns
a pointer to the transport's input buffer, NULL if no capacity available.

◆ pn_transport_push()

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.

Parameters
[in]transportthe transport
[in]srcthe start of the data to push into the transport
[in]sizethe amount of data to push into the transport
Returns
the number of bytes pushed on success, or error code if < 0

◆ pn_transport_process()

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.

Parameters
[in]transportthe transport
[in]sizethe amount of data written to the transport's input buffer
Returns
0 on success, or error code if < 0

◆ pn_transport_close_tail()

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.

Parameters
[in]transportthe transport
Returns
0 on success, or error code if < 0

◆ pn_transport_pending()

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.

Parameters
[in]transportthe transport
Returns
the number of pending output bytes, or an error code

◆ pn_transport_head()

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.

Parameters
[in]transportthe transport
Returns
a pointer to the transport's output buffer, or NULL if no pending output.

◆ pn_transport_peek()

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.

Parameters
[in]transportthe transport
[out]dstthe destination buffer
[in]sizethe capacity of the destination buffer
Returns
number of bytes copied on success, or error code if < 0

◆ pn_transport_pop()

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.

Parameters
[in]transportthe transport
[in]sizethe number of bytes to remove

◆ pn_transport_close_head()

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.

Parameters
[in]transportthe transport
Returns
0 on success, or error code if < 0

◆ pn_transport_quiesced()

bool pn_transport_quiesced ( pn_transport_t transport)

Deprecated - Use the Connection driver API.

Check if a transport has buffered data.

Parameters
[in]transporta transport object
Returns
true if the transport has buffered data, false otherwise

◆ pn_transport_head_closed()

bool pn_transport_head_closed ( pn_transport_t transport)

Deprecated - Use the Connection driver API.

True if pn_transport_close_head() has been called.

◆ pn_transport_tail_closed()

bool pn_transport_tail_closed ( pn_transport_t transport)

Deprecated - Use the Connection driver API.

True if pn_transport_close_tail() has been called.

◆ pn_transport_closed()

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)

◆ pn_transport_tick()

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.

Parameters
[in]transportthe transport to process.
[in]nowA monotonically-increasing time value in milliseconds. Does not need to be wall-clock time or a valid AMQP timestamp, but must increase montonically.
Returns
If non-zero, then the monotonic expiration time of the next pending timer event for the transport. The caller must invoke pn_transport_tick again at least once at or before this deadline occurs. If 0 there are no pending events.

◆ pn_transport_get_frames_output()

uint64_t pn_transport_get_frames_output ( const pn_transport_t transport)

Deprecated - No replacement.

Get the number of frames output by a transport.

Parameters
[in]transporta transport object
Returns
the number of frames output by the transport

◆ pn_transport_get_frames_input()

uint64_t pn_transport_get_frames_input ( const pn_transport_t transport)

Deprecated - No replacement.

Get the number of frames input by a transport.

Parameters
[in]transporta transport object
Returns
the number of frames input by the transport

◆ pn_transport_connection()

pn_connection_t* pn_transport_connection ( pn_transport_t transport)

Access the AMQP Connection associated with the transport.

Parameters
[in]transporta transport object
Returns
the connection context for the transport, or NULL if none