proton-c/include/proton/transport.h

#ifndef PROTON_TRANSPORT_H
#define PROTON_TRANSPORT_H 1

/*
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 */

#include <proton/import_export.h>
#include <proton/type_compat.h>
#include <proton/condition.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @file
 *
 * Transport API for the proton Engine.
 *
 * @defgroup transport Transport
 * @ingroup engine
 * @{
 */

/**
 * 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_TRACE_OFF
 * - ::PN_TRACE_RAW
 * - ::PN_TRACE_FRM
 * - ::PN_TRACE_DRV
 *
 */
typedef int pn_trace_t;

/**
 * Callback for customizing logging behaviour.
 */
typedef void (*pn_tracer_t)(pn_transport_t *transport, const char *message);

/**
 * Turn logging off entirely.
 */
#define PN_TRACE_OFF (0)

/**
 * Log raw binary data into/out of the transport.
 */
#define PN_TRACE_RAW (1)

/**
 * Log frames into/out of the transport.
 */
#define PN_TRACE_FRM (2)

/**
 * Log driver related events, e.g. initialization, end of stream, etc.
 */
#define PN_TRACE_DRV (4)

/**
 * 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. See
 * pn_transport_bind().
 *
 * 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.
 *
 * @return pointer to new transport
 */
PN_EXTERN pn_transport_t *pn_transport(void);

/**
 * Configure a transport as a server
 *
 * @param[in] transport a transport object
 */
PN_EXTERN void pn_transport_set_server(pn_transport_t *transport);

/**
 * Free a transport object.
 *
 * When a transport is freed, it is automatically unbound from its
 * associated connection.
 *
 * @param[in] transport a transport object or NULL
 */
PN_EXTERN void pn_transport_free(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.
 *
 * @param[in] transport the transport
 *
 * @return
 * 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_EXTERN const char *pn_transport_get_user(pn_transport_t *transport);

/**
 * 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 an SASL layer but the ANONYMOUS mechanism
 *
 * The default if this option is not set is to allow unauthenticated connections.
 *
 * @param[in] transport the transport
 * @param[in] required boolean is true when authenticated connections are required
 */
PN_EXTERN void pn_transport_require_auth(pn_transport_t *transport, bool required);

/**
 * Tell whether the transport connection is authenticated
 *
 * Note that this property may not be stable until the PN_CONNECTION_REMOTE_OPEN
 * event is received.
 *
 * @param[in] transport the transport
 * @return bool representing authentication
 */
PN_EXTERN bool pn_transport_is_authenticated(pn_transport_t *transport);

/**
 * Set whether a non encrypted transport connection is allowed
 *
 * There are several ways within the AMQP protocol suite to get encrypted connections:
 * - Use TLS/SSL
 * - Use an SASL with a mechanism that supports saecurity layers
 *
 * The default if this option is not set is to allow unencrypted connections.
 *
 * @param[in] transport the transport
 * @param[in] required boolean is true when encrypted connections are required
 */
PN_EXTERN void pn_transport_require_encryption(pn_transport_t *transport, bool required);

/**
 * Tell whether the transport connection is encrypted
 *
 * Note that this property may not be stable until the PN_CONNECTION_REMOTE_OPEN
 * event is received.
 *
 * @param[in] transport the transport
 * @return bool representing encryption
 */
PN_EXTERN bool pn_transport_is_encrypted(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 condtion.
 *
 * The pointer returned by this operation is valid until the
 * transport object is freed.
 *
 * @param[in] transport the transport object
 * @return the transport's condition object
 */
PN_EXTERN pn_condition_t *pn_transport_condition(pn_transport_t *transport);

/**
 * @deprecated
 */
PN_EXTERN  pn_error_t *pn_transport_error(pn_transport_t *transport);

/**
 * Binds the transport to an AMQP connection.
 *
 * @return an error code, or 0 on success
 */
PN_EXTERN int pn_transport_bind(pn_transport_t *transport, pn_connection_t *connection);

/**
 * Unbinds a transport from its AMQP connection.
 *
 * @return an error code, or 0 on success
 */
PN_EXTERN int pn_transport_unbind(pn_transport_t *transport);

/**
 * 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.
 *
 * @param[in] transport a transport object
 * @param[in] trace the trace flags
 */
PN_EXTERN void pn_transport_trace(pn_transport_t *transport, pn_trace_t trace);

/**
 * 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.
 *
 * @param[in] transport a transport object
 * @param[in] tracer the tracing function
 */
PN_EXTERN void pn_transport_set_tracer(pn_transport_t *transport, pn_tracer_t tracer);

/**
 * Get the tracning function used by a transport.
 *
 * @param[in] transport a transport object
 * @return the tracing function used by a transport
 */
PN_EXTERN pn_tracer_t pn_transport_get_tracer(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.
 *
 * @param[in] transport the transport whose context is to be returned.
 * @return the application context for the transport object
 */
PN_EXTERN void *pn_transport_get_context(pn_transport_t *transport);

/**
 * @deprecated
 * Set a new application context for a transport object.
 *
 * The application context for a transport object may be retrieved using
 * ::pn_transport_get_context.
 *
 * @param[in] transport the transport object
 * @param[in] context the application context
 */
PN_EXTERN void pn_transport_set_context(pn_transport_t *transport, void *context);

/**
 * Get the attachments that are associated with a transport object.
 *
 * @param[in] transport the transport whose attachments are to be returned.
 * @return the attachments for the transport object
 */
PN_EXTERN pn_record_t *pn_transport_attachments(pn_transport_t *transport);

/**
 * 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.
 *
 * @param[in] transport a transport object
 * @param[in] message the message to be logged
 */
PN_EXTERN void pn_transport_log(pn_transport_t *transport, const char *message);

/**
 * 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.
 *
 * @param[in] transport a transport object
 * @param[in] fmt the printf formatted message to be logged
 * @param[in] ap a vector containing the format arguments
 */
PN_EXTERN 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.
 *
 * @param[in] transport a transport object
 * @param[in] fmt the printf formatted message to be logged
 */
PN_EXTERN void pn_transport_logf(pn_transport_t *transport, const char *fmt, ...);

/**
 * 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()
 *
 * @param[in] transport a transport object
 * @return the maximum allowed channel
 */
PN_EXTERN uint16_t pn_transport_get_channel_max(pn_transport_t *transport);

/**
 * 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 simultaineously 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.
 *
 * @param[in] transport a transport object
 * @param[in] channel_max the maximum allowed channel
 * @return PN_OK, or PN_STATE_ERR if it is too late to change channel_max
 */
PN_EXTERN int pn_transport_set_channel_max(pn_transport_t *transport, uint16_t channel_max);

/**
 * Get the maximum allowed channel of a transport's remote peer.
 *
 * @param[in] transport a transport object
 * @return the maximum allowed channel of the transport's remote peer
 */
PN_EXTERN uint16_t pn_transport_remote_channel_max(pn_transport_t *transport);

/**
 * Get the maximum frame size of a transport.
 *
 * @param[in] transport a transport object
 * @return the maximum frame size of the transport object
 */
PN_EXTERN uint32_t pn_transport_get_max_frame(pn_transport_t *transport);

/**
 * Set the maximum frame size of a transport.
 *
 * @param[in] transport a transport object
 * @param[in] size the maximum frame size for the transport object
 */
PN_EXTERN void pn_transport_set_max_frame(pn_transport_t *transport, uint32_t size);

/**
 * Get the maximum frame size of a transport's remote peer.
 *
 * @param[in] transport a transport object
 * @return the maximum frame size of the transport's remote peer
 */
PN_EXTERN uint32_t pn_transport_get_remote_max_frame(pn_transport_t *transport);

/**
 * Get the idle timeout for a transport.
 *
 * A zero idle timeout means heartbeats are disabled.
 *
 * @param[in] transport a transport object
 * @return the transport's idle timeout
 */
PN_EXTERN pn_millis_t pn_transport_get_idle_timeout(pn_transport_t *transport);

/**
 * Set the idle timeout for a transport.
 *
 * A zero idle timeout means heartbeats are disabled.
 *
 * @param[in] transport a transport object
 * @param[in] timeout the idle timeout for the transport object
 */
PN_EXTERN void pn_transport_set_idle_timeout(pn_transport_t *transport, pn_millis_t timeout);

/**
 * Get the idle timeout for a transport's remote peer.
 *
 * A zero idle timeout means heartbeats are disabled.
 *
 * @param[in] transport a transport object
 * @return the idle timeout for the transport's remote peer
 */
PN_EXTERN pn_millis_t pn_transport_get_remote_idle_timeout(pn_transport_t *transport);

/**
 * @deprecated
 */
PN_EXTERN ssize_t pn_transport_input(pn_transport_t *transport, const char *bytes, size_t available);
/**
 * @deprecated
 */
PN_EXTERN ssize_t pn_transport_output(pn_transport_t *transport, char *bytes, size_t size);

/**
 * 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, futher details can be obtained from
 * ::pn_transport_error. Calls to ::pn_transport_process may alter the
 * value of this pointer. See ::pn_transport_process for details.
 *
 * @param[in] transport the transport
 * @return the free space in the transport, PN_EOS or error code if < 0
 */
PN_EXTERN ssize_t pn_transport_capacity(pn_transport_t *transport);

/**
 * 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 alther
 * the value of this pointer. See ::pn_transport_process for details.
 *
 * @param[in] transport the transport
 * @return a pointer to the transport's input buffer, NULL if no capacity available.
 */
PN_EXTERN char *pn_transport_tail(pn_transport_t *transport);

/**
 * Pushes the supplied bytes into the tail of the transport.
 *
 * This is equivalent to copying @c size bytes afther the tail pointer
 * and then calling ::pn_transport_process with an argument of @c
 * size. Only some of the bytes will be copied if there is
 * insufficienty capacity available. Use ::pn_transport_capacity to
 * determine how much capacity the transport has.
 *
 * @param[in] transport the transport
 * @param[in] src the start of the data to push into the transport
 * @param[in] size the amount of data to push into the transport
 *
 * @return the number of bytes pushed on success, or error code if < 0
 */
PN_EXTERN ssize_t pn_transport_push(pn_transport_t *transport, const char *src, size_t size);

/**
 * Process input data following the tail pointer.
 *
 * Calling this function will cause the transport to consume @c 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.
 *
 * @param[in] transport the transport
 * @param[in] size the amount of data written to the transport's input buffer
 * @return 0 on success, or error code if < 0
 */
PN_EXTERN int pn_transport_process(pn_transport_t *transport, size_t size);

/**
 * Indicate that the input has reached End Of Stream (EOS).
 *
 * This tells the transport that no more input will be forthcoming.
 *
 * @param[in] transport the transport
 * @return 0 on success, or error code if < 0
 */
PN_EXTERN int pn_transport_close_tail(pn_transport_t *transport);

/**
 * 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_error. Calls to ::pn_transport_pop may alter the
 * value of this pointer. See ::pn_transport_pop for details.
 *
 * @param[in] transport the transport
 * @return the number of pending output bytes, or an error code
 */
PN_EXTERN ssize_t pn_transport_pending(pn_transport_t *transport);

/**
 * 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.
 *
 * @param[in] transport the transport
 * @return a pointer to the transport's output buffer, or NULL if no pending output.
 */
PN_EXTERN const char *pn_transport_head(pn_transport_t *transport);

/**
 * Copies @c size bytes from the head of the transport to the @c dst
 * pointer.
 *
 * It is an error to call this with a value of @c size that is greater
 * than the value reported by ::pn_transport_pending.
 *
 * @param[in] transport the transport
 * @param[out] dst the destination buffer
 * @param[in] size the capacity of the destination buffer
 * @return number of bytes copied on success, or error code if < 0
 */
PN_EXTERN ssize_t pn_transport_peek(pn_transport_t *transport, char *dst, size_t size);

/**
 * Removes @c 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.
 *
 * @param[in] transport the transport
 * @param[in] size the number of bytes to remove
 */
PN_EXTERN void pn_transport_pop(pn_transport_t *transport, size_t size);

/**
 * Indicate that the output has closed.
 *
 * This tells the transport that no more output will be popped.
 *
 * @param[in] transport the transport
 * @return 0 on success, or error code if < 0
 */
PN_EXTERN int pn_transport_close_head(pn_transport_t *transport);

/**
 * Check if a transport has buffered data.
 *
 * @param[in] transport a transport object
 * @return true if the transport has buffered data, false otherwise
 */
PN_EXTERN bool pn_transport_quiesced(pn_transport_t *transport);

/**
 * Check if a transport is closed.
 *
 * A transport is defined to be closed when both the tail and the head
 * are closed. In other words, when both ::pn_transport_capacity() < 0
 * and ::pn_transport_pending() < 0.
 *
 * @param[in] transport a transport object
 * @return true if the transport is closed, false otherwise
 */
PN_EXTERN bool pn_transport_closed(pn_transport_t *transport);

/**
 * Process any pending transport timer events.
 *
 * This method should be called after all pending input has been
 * processed by the transport (see ::pn_transport_input), and before
 * generating output (see ::pn_transport_output). It returns the
 * deadline for the next pending timer event, if any are present.
 *
 * @param[in] transport the transport to process.
 * @param[in] now the current time
 *
 * @return if non-zero, then the 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.
 */
PN_EXTERN pn_timestamp_t pn_transport_tick(pn_transport_t *transport, pn_timestamp_t now);

/**
 * Get the number of frames output by a transport.
 *
 * @param[in] transport a transport object
 * @return the number of frames output by the transport
 */
PN_EXTERN uint64_t pn_transport_get_frames_output(const pn_transport_t *transport);

/**
 * Get the number of frames input by a transport.
 *
 * @param[in] transport a transport object
 * @return the number of frames input by the transport
 */
PN_EXTERN uint64_t pn_transport_get_frames_input(const pn_transport_t *transport);

/** Access the AMQP Connection associated with the transport.
 *
 * @param[in] transport a transport object
 * @return the connection context for the transport, or NULL if
 *         none
 */
PN_EXTERN pn_connection_t *pn_transport_connection(pn_transport_t *transport);

#ifdef __cplusplus
}
#endif

/** @}
 */

#endif /* transport.h */