You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by rh...@apache.org on 2014/03/14 12:01:54 UTC

svn commit: r1577478 - /qpid/proton/trunk/proton-c/include/proton/transport.h

Author: rhs
Date: Fri Mar 14 11:01:53 2014
New Revision: 1577478

URL: http://svn.apache.org/r1577478
Log:
doxygen for transport.h

Modified:
    qpid/proton/trunk/proton-c/include/proton/transport.h

Modified: qpid/proton/trunk/proton-c/include/proton/transport.h
URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-c/include/proton/transport.h?rev=1577478&r1=1577477&r2=1577478&view=diff
==============================================================================
--- qpid/proton/trunk/proton-c/include/proton/transport.h (original)
+++ qpid/proton/trunk/proton-c/include/proton/transport.h Fri Mar 14 11:01:53 2014
@@ -33,7 +33,9 @@
 extern "C" {
 #endif
 
-/** @file
+/**
+ * @file
+ *
  * Transport API for the proton Engine.
  *
  * @defgroup transport Transport
@@ -41,68 +43,295 @@ extern "C" {
  * @{
  */
 
+/**
+ * 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.
+/**
+ * Factory for creating a transport.
  *
- * A transport to be used by a connection to interface with the
- * network. There can only be one connection associated with a
- * transport. See pn_transport_bind().
+ * 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().
  *
  * @return pointer to new transport
  */
 PN_EXTERN pn_transport_t *pn_transport(void);
 
-/** Binds the transport to an AMQP connection endpoint.
+/**
+ * Free a transport object.
  *
- * @return an error code, or 0 on success
+ * 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);
+
+/**
+ * Get additional error information associated with the transport.
+ *
+ * Whenever a transport operation fails (i.e. returns an error code),
+ * additional error details can be obtained using this function. The
+ * error object that is returned may also be used to clear the error
+ * condition.
+ *
+ * The pointer returned by this operation is valid until the
+ * transport object is freed.
+ *
+ * @param[in] transport the transport object
+ * @return the transport's error object
  */
+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);
 
-PN_EXTERN pn_error_t *pn_transport_error(pn_transport_t *transport);
-/* deprecated */
+/**
+ * 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);
+
+/**
+ * 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);
+
+/**
+ * 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
+ */
+PN_EXTERN void pn_transport_logf(pn_transport_t *transport, const char *fmt, ...);
+
+/**
+ * Get the maximum allowed channel for a transport.
+ *
+ * @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 for a transport.
+ *
+ * @param[in] transport a transport object
+ * @param[in] channel_max the maximum allowed channel
+ */
+PN_EXTERN void 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 */
+/**
+ * @deprecated
+ */
 PN_EXTERN ssize_t pn_transport_output(pn_transport_t *transport, char *bytes, size_t size);
 
-/** Report 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.
+/**
+ * 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);
 
-/** Return 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.
+/**
+ * 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. It
- * is an error to call this with a @c size larger than the capacity
- * reported by ::pn_transport_capacity.
+/**
+ * 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. It is an error to call this with a @c size larger than the
+ * capacity reported by ::pn_transport_capacity.
  *
  * @param[in] transport the transport
  * @param[in] src the start of the data to push into the transport
@@ -112,11 +341,14 @@ PN_EXTERN char *pn_transport_tail(pn_tra
  */
 PN_EXTERN int 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.
+/**
+ * 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
@@ -124,42 +356,52 @@ PN_EXTERN int pn_transport_push(pn_trans
  */
 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.
+/**
+ * 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);
 
-/** Report 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.
+/**
+ * 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);
 
-/** Return 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.
+/**
+ * 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.
+/**
+ * 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
@@ -168,31 +410,56 @@ PN_EXTERN const char *pn_transport_head(
  */
 PN_EXTERN int 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.
+/**
+ * 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.
+/**
+ * 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.
+/**
+ * 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.
+ * 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
@@ -202,33 +469,22 @@ PN_EXTERN int pn_transport_close_head(pn
  * this deadline occurs.
  */
 PN_EXTERN pn_timestamp_t pn_transport_tick(pn_transport_t *transport, pn_timestamp_t now);
-PN_EXTERN void pn_transport_trace(pn_transport_t *transport, pn_trace_t trace);
-PN_EXTERN void pn_transport_set_tracer(pn_transport_t *transport, pn_tracer_t tracer);
-PN_EXTERN pn_tracer_t pn_transport_get_tracer(pn_transport_t *transport);
-PN_EXTERN void pn_transport_set_context(pn_transport_t *transport, void *context);
-PN_EXTERN void *pn_transport_get_context(pn_transport_t *transport);
-PN_EXTERN void pn_transport_log(pn_transport_t *transport, const char *message);
-PN_EXTERN void pn_transport_logf(pn_transport_t *transport, const char *fmt, ...);
-
-PN_EXTERN uint16_t pn_transport_get_channel_max(pn_transport_t *transport);
-PN_EXTERN void pn_transport_set_channel_max(pn_transport_t *transport, uint16_t channel_max);
-PN_EXTERN uint16_t pn_transport_remote_channel_max(pn_transport_t *transport);
-
-// max frame of zero means "unlimited"
-PN_EXTERN uint32_t pn_transport_get_max_frame(pn_transport_t *transport);
-PN_EXTERN void pn_transport_set_max_frame(pn_transport_t *transport, uint32_t size);
-PN_EXTERN uint32_t pn_transport_get_remote_max_frame(pn_transport_t *transport);
-
-/* timeout of zero means "no timeout" */
-PN_EXTERN pn_millis_t pn_transport_get_idle_timeout(pn_transport_t *transport);
-PN_EXTERN void pn_transport_set_idle_timeout(pn_transport_t *transport, pn_millis_t timeout);
-PN_EXTERN pn_millis_t pn_transport_get_remote_idle_timeout(pn_transport_t *transport);
 
+/**
+ * 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);
-PN_EXTERN bool pn_transport_quiesced(pn_transport_t *transport);
-PN_EXTERN bool pn_transport_closed(pn_transport_t *transport);
-PN_EXTERN void pn_transport_free(pn_transport_t *transport);
 
 #ifdef __cplusplus
 }



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org