qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From r..@apache.org
Subject svn commit: r1576508 - in /qpid/proton/trunk/proton-c/include/proton: condition.h connection.h engine.h types.h
Date Tue, 11 Mar 2014 21:26:11 GMT
Author: rhs
Date: Tue Mar 11 21:26:10 2014
New Revision: 1576508

URL: http://svn.apache.org/r1576508
Log:
added doxygen for condition.h and connection.h

Modified:
    qpid/proton/trunk/proton-c/include/proton/condition.h
    qpid/proton/trunk/proton-c/include/proton/connection.h
    qpid/proton/trunk/proton-c/include/proton/engine.h
    qpid/proton/trunk/proton-c/include/proton/types.h

Modified: qpid/proton/trunk/proton-c/include/proton/condition.h
URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-c/include/proton/condition.h?rev=1576508&r1=1576507&r2=1576508&view=diff
==============================================================================
--- qpid/proton/trunk/proton-c/include/proton/condition.h (original)
+++ qpid/proton/trunk/proton-c/include/proton/condition.h Tue Mar 11 21:26:10 2014
@@ -35,7 +35,8 @@ extern "C" {
 #endif
 
 /** @file
- * Condition API for the proton Engine.
+ *
+ * The Condition API for the proton Engine.
  *
  * @defgroup condition Condition
  * @ingroup connection
@@ -43,23 +44,122 @@ extern "C" {
  */
 
 /**
- * Represents an AMQP Condition.
+ * An AMQP Condition object. Conditions hold exceptional information
+ * pertaining to the closing of an AMQP endpoint such as a Connection,
+ * Session, or Link. Conditions also hold similar information
+ * pertaining to deliveries that have reached terminal states.
+ * Connections, Sessions, Links, and Deliveries may all have local and
+ * remote conditions associated with them.
+ *
+ * The local condition may be modified by the local endpoint to signal
+ * a particular condition to the remote peer. The remote condition may
+ * be examined by the local endpoint to detect whatever condition the
+ * remote peer may be signaling. Although often conditions are used to
+ * indicate errors, not all conditions are errors per/se, e.g.
+ * conditions may be used to redirect a connection from one host to
+ * another.
+ *
+ * Every condition has a short symbolic name, a longer description,
+ * and an additional info map associated with it. The name identifies
+ * the formally defined condition, and the map contains additional
+ * information relevant to the identified condition.
  */
 typedef struct pn_condition_t pn_condition_t;
 
+/**
+ * Returns true if the condition object is holding some information,
+ * i.e. if the name is set to some non NULL value. Returns false
+ * otherwise.
+ *
+ * @param[in] condition the condition object to test
+ * @return true iff some condition information is set
+ */
 PN_EXTERN bool pn_condition_is_set(pn_condition_t *condition);
+
+/**
+ * Clears the condition object of any exceptional information. After
+ * calling ::pn_condition_clear(), ::pn_condition_is_set() is
+ * guaranteed to return false and ::pn_condition_get_name() as well as
+ * ::pn_condition_get_description() will return NULL. The ::pn_data_t
+ * returned by ::pn_condition_info() will still be valid, but will
+ * have been cleared as well (See ::pn_data_clear()).
+ *
+ * @param[in] condition the condition object to clear
+ */
 PN_EXTERN void pn_condition_clear(pn_condition_t *condition);
 
+/**
+ * Returns the name associated with the exceptional condition, or NULL
+ * if there is no conditional information set.
+ *
+ * @param[in] condition the condition object
+ * @return a pointer to the name, or NULL
+ */
 PN_EXTERN const char *pn_condition_get_name(pn_condition_t *condition);
+
+/**
+ * Sets the name associated with the exceptional condition.
+ *
+ * @param[in] condition the condition object
+ * @param[in] name the desired name
+ * @return an error code or 0 on success
+ */
 PN_EXTERN int pn_condition_set_name(pn_condition_t *condition, const char *name);
 
+/**
+ * Gets the description associated with the exceptional condition.
+ *
+ * @param[in] condition the condition object
+ * @return a pointer to the description, or NULL
+ */
 PN_EXTERN const char *pn_condition_get_description(pn_condition_t *condition);
+
+/**
+ * Sets the description associated with the exceptional condition.
+ *
+ * @param[in] condition the condition object
+ * @param[in] description the desired description
+ * @return an error code or 0 on success
+ */
 PN_EXTERN int pn_condition_set_description(pn_condition_t *condition, const char *description);
 
+/**
+ * Returns a data object that holds the additional information
+ * associated with the condition. The data object may be used both to
+ * access and to modify the additional information associated with the
+ * condition.
+ *
+ * @param[in] condition the condition object
+ * @return a data object holding the additional information for the condition
+ */
 PN_EXTERN pn_data_t *pn_condition_info(pn_condition_t *condition);
 
+/**
+ * Returns true if the condition is a redirect.
+ *
+ * @param[in] condition the condition object
+ * @return true if the condition is a redirect, false otherwise
+ */
 PN_EXTERN bool pn_condition_is_redirect(pn_condition_t *condition);
+
+/**
+ * Retrieves the redirect host from the additional information
+ * associated with the condition. If the condition is not a redirect,
+ * this will return NULL.
+ *
+ * @param[in] condition the condition object
+ * @return the redirect host or NULL
+ */
 PN_EXTERN const char *pn_condition_redirect_host(pn_condition_t *condition);
+
+/**
+ * Retrieves the redirect port from the additional information
+ * associated with the condition. If the condition is not a redirect,
+ * this will return an error code.
+ *
+ * @param[in] condition the condition object
+ * @return the redirect port or an error code
+ */
 PN_EXTERN int pn_condition_redirect_port(pn_condition_t *condition);
 
 /** @}

Modified: qpid/proton/trunk/proton-c/include/proton/connection.h
URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-c/include/proton/connection.h?rev=1576508&r1=1576507&r2=1576508&view=diff
==============================================================================
--- qpid/proton/trunk/proton-c/include/proton/connection.h (original)
+++ qpid/proton/trunk/proton-c/include/proton/connection.h Tue Mar 11 21:26:10 2014
@@ -33,7 +33,9 @@
 extern "C" {
 #endif
 
-/** @file
+/**
+ * @file
+ *
  * Connection API for the proton Engine.
  *
  * @defgroup connection Connection
@@ -41,72 +43,369 @@ extern "C" {
  * @{
  */
 
-#define PN_LOCAL_UNINIT (1)    /**< local endpoint requires initialization */
-#define PN_LOCAL_ACTIVE (2)    /**< local endpoint is active */
-#define PN_LOCAL_CLOSED (4)    /**< local endpoint is closed */
-#define PN_REMOTE_UNINIT (8)   /**< remote endpoint pending initialization by peer */
-#define PN_REMOTE_ACTIVE (16)  /**< remote endpoint is active */
-#define PN_REMOTE_CLOSED (32)  /**< remote endpoint has closed */
+/**
+ * The local @link pn_state_t endpoint state @endlink is uninitialized.
+ */
+#define PN_LOCAL_UNINIT (1)
+/**
+ * The local @link pn_state_t endpoint state @endlink is active.
+ */
+#define PN_LOCAL_ACTIVE (2)
+/**
+ * The local @link pn_state_t endpoint state @endlink is closed.
+ */
+#define PN_LOCAL_CLOSED (4)
+/**
+ * The remote @link pn_state_t endpoint state @endlink is uninitialized.
+ */
+#define PN_REMOTE_UNINIT (8)
+/**
+ * The remote @link pn_state_t endpoint state @endlink is active.
+ */
+#define PN_REMOTE_ACTIVE (16)
+/**
+ * The remote @link pn_state_t endpoint state @endlink is closed.
+ */
+#define PN_REMOTE_CLOSED (32)
 
+/**
+ * A mask for values of ::pn_state_t that preserves only the local
+ * bits of an endpoint's state.
+ */
 #define PN_LOCAL_MASK (PN_LOCAL_UNINIT | PN_LOCAL_ACTIVE | PN_LOCAL_CLOSED)
+
+/**
+ * A mask for values of ::pn_state_t that preserves only the remote
+ * bits of an endpoint's state.
+ */
 #define PN_REMOTE_MASK (PN_REMOTE_UNINIT | PN_REMOTE_ACTIVE | PN_REMOTE_CLOSED)
 
-/** Factory to construct a new Connection.
+/**
+ * Factory to construct a new Connection.
  *
  * @return pointer to a new connection object.
  */
 PN_EXTERN pn_connection_t *pn_connection(void);
 
+/**
+ * Free a connection object.
+ *
+ * When a connection object is freed, all ::pn_session_t, ::pn_link_t,
+ * and ::pn_delivery_t objects associated with the connection are also
+ * freed.
+ *
+ * @param[in] connection the connection object to free (or NULL)
+ */
+PN_EXTERN void pn_connection_free(pn_connection_t *connection);
+
+/**
+ * Get additional error information associated with the connection.
+ *
+ * Whenever a connection 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
+ * connection object is freed.
+ *
+ * @param[in] connection the connection object
+ * @return the connection's error object
+ */
+PN_EXTERN pn_error_t *pn_connection_error(pn_connection_t *connection);
+
+/**
+ * Associate a connection object with an event collector.
+ *
+ * By associating a connection object with an event collector, key
+ * changes in endpoint state are reported to the collector via
+ * ::pn_event_t objects that can be inspected and processed. See
+ * ::pn_event_t for more details on the kinds of events.
+ *
+ * Note that by registering a collector, the user is requesting that
+ * an indefinite number of events be queued up on his behalf. This
+ * means that unless the application eventually processes these
+ * events, the storage requirements for keeping them will grow without
+ * bound. In other words, don't register a collector with a connection
+ * if you never intend to process any of the events.
+ *
+ * @param[in] connection the connection object
+ * @param[in] collector the event collector
+ */
 PN_EXTERN void pn_connection_collect(pn_connection_t *connection, pn_collector_t *collector);
 
-/** Retrieve the state of the connection.
+/**
+ * Get the application context that is associated with a connection
+ * object.
+ *
+ * The application context for a connection may be set using
+ * ::pn_connection_set_context.
+ *
+ * @param[in] connection the connection whose context is to be returned.
+ * @return the application context for the connection object
+ */
+PN_EXTERN void *pn_connection_get_context(pn_connection_t *connection);
+
+/**
+ * Set a new application context for a connection object.
+ *
+ * The application context for a connection object may be retrieved
+ * using ::pn_connection_get_context.
+ *
+ * @param[in] connection the connection object
+ * @param[in] context the application context
+ */
+PN_EXTERN void pn_connection_set_context(pn_connection_t *connection, void *context);
+
+/**
+ * Get the endpoint state flags for a connection.
  *
  * @param[in] connection the connection
  * @return the connection's state flags
  */
 PN_EXTERN pn_state_t pn_connection_state(pn_connection_t *connection);
-/** @todo: needs documentation */
-PN_EXTERN pn_error_t *pn_connection_error(pn_connection_t *connection);
+
+/**
+ * Open a connection object.
+ *
+ * Once this operation has completed, the PN_LOCAL_ACTIVE state flag
+ * will be set.
+ *
+ * @param[in] connection the connection object
+ */
+PN_EXTERN void pn_connection_open(pn_connection_t *connection);
+
+/**
+ * Close a connection object.
+ *
+ * Once this operation has completed, the PN_LOCAL_CLOSED state flag
+ * will be set. This may be called without calling
+ * ::pn_connection_open, in this case it is equivalent to calling
+ * ::pn_connection_open followed by ::pn_connection_close.
+ *
+ * @param[in] connection the connection object
+ */
+PN_EXTERN void pn_connection_close(pn_connection_t *connection);
+
+/**
+ * Reset a connection object back to the uninitialized state.
+ *
+ * Note that this does *not* remove any contained ::pn_session_t,
+ * ::pn_link_t, and ::pn_delivery_t objects.
+ *
+ * @param[in] connection the connection object
+ */
+PN_EXTERN void pn_connection_reset(pn_connection_t *connection);
+
+/**
+ * Get the local condition associated with the connection endpoint.
+ *
+ * The ::pn_condition_t object retrieved may be modified prior to
+ * closing the connection in order to indicate a particular condition
+ * exists when the connection closes. This is normally used to
+ * communicate error conditions to the remote peer, however it may
+ * also be used in non error cases such as redirects. See
+ * ::pn_condition_t for more details.
+ *
+ * The pointer returned by this operation is valid until the
+ * connection object is freed.
+ *
+ * @param[in] connection the connection object
+ * @return the connection's local condition object
+ */
 PN_EXTERN pn_condition_t *pn_connection_condition(pn_connection_t *connection);
+
+/**
+ * Get the remote condition associated with the connection endpoint.
+ *
+ * The ::pn_condition_t object retrieved may be examined in order to
+ * determine whether the remote peer was indicating some sort of
+ * exceptional condition when the remote connection endpoint was
+ * closed. The ::pn_condition_t object returned may not be modified.
+ *
+ * The pointer returned by this operation is valid until the
+ * connection object is freed.
+ *
+ * @param[in] connection the connection object
+ * @return the connection's remote condition object
+ */
 PN_EXTERN pn_condition_t *pn_connection_remote_condition(pn_connection_t *connection);
-/** @todo: needs documentation */
+
+/**
+ * Get the AMQP Container name advertised by a connection object.
+ *
+ * The pointer returned by this operation is valid until
+ * ::pn_connection_set_container is called, or until the connection
+ * object is freed, whichever happens sooner.
+ *
+ * @param[in] connection the connection object
+ * @return a pointer to the container name
+ */
 PN_EXTERN const char *pn_connection_get_container(pn_connection_t *connection);
-/** @todo: needs documentation */
+
+/**
+ * Set the AMQP Container name advertised by a connection object.
+ *
+ * @param[in] connection the connection object
+ * @param[in] container the container name
+ */
 PN_EXTERN void pn_connection_set_container(pn_connection_t *connection, const char *container);
-/** @todo: needs documentation */
+
+/**
+ * Get the value of the AMQP Hostname used by a connection object.
+ *
+ * The pointer returned by this operation is valid until
+ * ::pn_connection_set_hostname is called, or until the connection
+ * object is freed, whichever happens sooner.
+ *
+ * @param[in] connection the connection object
+ * @return a pointer to the hostname
+ */
 PN_EXTERN const char *pn_connection_get_hostname(pn_connection_t *connection);
-/** @todo: needs documentation */
+
+/**
+ * Set the value of the AMQP Hostname used by a connection object.
+ *
+ * @param[in] connection the connection object
+ * @param[in] hostname the hostname
+ */
 PN_EXTERN void pn_connection_set_hostname(pn_connection_t *connection, const char *hostname);
+
+/**
+ * Get the AMQP Container name advertised by the remote connection
+ * endpoint.
+ *
+ * This will return NULL until the ::PN_REMOTE_ACTIVE state is
+ * reached. See ::pn_state_t for more details on endpoint state.
+ *
+ * Any non null pointer returned by this operation will be valid until
+ * the connection object is unbound from a transport or freed,
+ * whichever happens sooner.
+ *
+ * @param[in] connection the connection object
+ * @return a pointer to the remote container name
+ */
 PN_EXTERN const char *pn_connection_remote_container(pn_connection_t *connection);
+
+/**
+ * Get the AMQP Hostname set by the remote connection endpoint.
+ *
+ * This will return NULL until the ::PN_REMOTE_ACTIVE state is
+ * reached. See ::pn_state_t for more details on endpoint state.
+ *
+ * Any non null pointer returned by this operation will be valid until
+ * the connection object is unbound from a transport or freed,
+ * whichever happens sooner.
+ *
+ * @param[in] connection the connection object
+ * @return a pointer to the remote hostname
+ */
 PN_EXTERN const char *pn_connection_remote_hostname(pn_connection_t *connection);
+
+/**
+ * Access/modify the AMQP offered capabilities data for a connection
+ * object.
+ *
+ * This operation will return a pointer to a ::pn_data_t object that
+ * is valid until the connection object is freed. Any data contained
+ * by the ::pn_data_t object will be sent as the offered capabilites
+ * for the parent connection object. Note that this MUST take the form
+ * of an array of symbols to be valid.
+ *
+ * The ::pn_data_t pointer returned is valid until the connection
+ * object is freed.
+ *
+ * @param[in] connection the connection object
+ * @return a pointer to a pn_data_t representing the offered capabilities
+ */
 PN_EXTERN pn_data_t *pn_connection_offered_capabilities(pn_connection_t *connection);
+
+/**
+ * Access/modify the AMQP desired capabilities data for a connection
+ * object.
+ *
+ * This operation will return a pointer to a ::pn_data_t object that
+ * is valid until the connection object is freed. Any data contained
+ * by the ::pn_data_t object will be sent as the desired capabilites
+ * for the parent connection object. Note that this MUST take the form
+ * of an array of symbols to be valid.
+ *
+ * The ::pn_data_t pointer returned is valid until the connection
+ * object is freed.
+ *
+ * @param[in] connection the connection object
+ * @return a pointer to a pn_data_t representing the desired capabilities
+ */
 PN_EXTERN pn_data_t *pn_connection_desired_capabilities(pn_connection_t *connection);
+
+/**
+ * Access/modify the AMQP properties data for a connection object.
+ *
+ * This operation will return a pointer to a ::pn_data_t object that
+ * is valid until the connection object is freed. Any data contained
+ * by the ::pn_data_t object will be sent as the AMQP properties for
+ * the parent connection object. Note that this MUST take the form of
+ * a symbol keyed map to be valid.
+ *
+ * The ::pn_data_t pointer returned is valid until the connection
+ * object is freed.
+ *
+ * @param[in] connection the connection object
+ * @return a pointer to a pn_data_t representing the connection properties
+ */
 PN_EXTERN pn_data_t *pn_connection_properties(pn_connection_t *connection);
+
+/**
+ * Access the AMQP offered capabilites supplied by the remote
+ * connection endpoint.
+ *
+ * This operation will return a pointer to a ::pn_data_t object that
+ * is valid until the connection object is freed. This data object
+ * will be empty until the remote connection is opened as indicated by
+ * the ::PN_REMOTE_ACTIVE flag.
+ *
+ * @param[in] connection the connection object
+ * @return the remote offered capabilities
+ */
 PN_EXTERN pn_data_t *pn_connection_remote_offered_capabilities(pn_connection_t *connection);
-PN_EXTERN pn_data_t *pn_connection_remote_desired_capabilities(pn_connection_t *connection);
-PN_EXTERN pn_data_t *pn_connection_remote_properties(pn_connection_t *connection);
-PN_EXTERN void pn_connection_reset(pn_connection_t *connection);
-PN_EXTERN void pn_connection_open(pn_connection_t *connection);
-PN_EXTERN void pn_connection_close(pn_connection_t *connection);
-PN_EXTERN void pn_connection_free(pn_connection_t *connection);
 
-/** Access the application context that is associated with the
- *  connection.
+/**
+ * Access the AMQP desired capabilites supplied by the remote
+ * connection endpoint.
  *
- * @param[in] connection the connection whose context is to be returned.
+ * This operation will return a pointer to a ::pn_data_t object that
+ * is valid until the connection object is freed. This data object
+ * will be empty until the remote connection is opened as indicated by
+ * the ::PN_REMOTE_ACTIVE flag.
  *
- * @return the application context that was passed to pn_connection_set_context()
+ * @param[in] connection the connection object
+ * @return the remote desired capabilities
  */
-PN_EXTERN void *pn_connection_get_context(pn_connection_t *connection);
+PN_EXTERN pn_data_t *pn_connection_remote_desired_capabilities(pn_connection_t *connection);
 
-/** Assign a new application context to the connection.
+/**
+ * Access the AMQP connection properties supplied by the remote
+ * connection endpoint.
+ *
+ * This operation will return a pointer to a ::pn_data_t object that
+ * is valid until the connection object is freed. This data object
+ * will be empty until the remote connection is opened as indicated by
+ * the ::PN_REMOTE_ACTIVE flag.
  *
- * @param[in] connection the connection which will hold the context.
- * @param[in] context new application context to associate with the
- *                    connection
+ * @param[in] connection the connection object
+ * @return the remote connection properties
  */
-PN_EXTERN void pn_connection_set_context(pn_connection_t *connection, void *context);
+PN_EXTERN pn_data_t *pn_connection_remote_properties(pn_connection_t *connection);
 
+/**
+ * Get the transport bound to a connection object.
+ *
+ * If the connection is unbound, then this operation will return NULL.
+ *
+ * @param[in] connection the connection object
+ * @return the transport bound to a connection, or NULL if the
+ * connection is unbound
+ */
 PN_EXTERN pn_transport_t *pn_connection_transport(pn_connection_t *connection);
 
 /** @}

Modified: qpid/proton/trunk/proton-c/include/proton/engine.h
URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-c/include/proton/engine.h?rev=1576508&r1=1576507&r2=1576508&view=diff
==============================================================================
--- qpid/proton/trunk/proton-c/include/proton/engine.h (original)
+++ qpid/proton/trunk/proton-c/include/proton/engine.h Tue Mar 11 21:26:10 2014
@@ -23,7 +23,9 @@
  */
 
 /** @file
- * API for the proton Engine.
+ *
+ * The proton Engine API. The Engine API provides a complete
+ * implementation of AMQP as a Protocol Engine.
  *
  * @defgroup engine Engine
  */

Modified: qpid/proton/trunk/proton-c/include/proton/types.h
URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-c/include/proton/types.h?rev=1576508&r1=1576507&r2=1576508&view=diff
==============================================================================
--- qpid/proton/trunk/proton-c/include/proton/types.h (original)
+++ qpid/proton/trunk/proton-c/include/proton/types.h Tue Mar 11 21:26:10 2014
@@ -76,45 +76,97 @@ PN_EXTERN pn_bytes_t pn_bytes_dup(size_t
  * @{
  */
 
-/**
- * Encodes the state of an endpoint.
+/** Holds the state flags for an AMQP endpoint.
+ *
+ * A pn_state_t is an integral value with flags that encode both the
+ * local and remote state of an AMQP Endpoint (@link pn_connection_t
+ * Connection @endlink, @link pn_session_t Session @endlink, or @link
+ * pn_link_t Link @endlink). The local portion of the state may be
+ * accessed using ::PN_LOCAL_MASK, and the remote portion may be
+ * accessed using ::PN_REMOTE_MASK. Individual bits may be accessed
+ * using ::PN_LOCAL_UNINIT, ::PN_LOCAL_ACTIVE, ::PN_LOCAL_CLOSED, and
+ * ::PN_REMOTE_UNINIT, ::PN_REMOTE_ACTIVE, ::PN_REMOTE_CLOSED.
+ *
+ * Every AMQP endpoint (@link pn_connection_t Connection @endlink,
+ * @link pn_session_t Session @endlink, or @link pn_link_t Link
+ * @endlink) starts out in an uninitialized state and then proceeds
+ * linearly to an active and then closed state. This lifecycle occurs
+ * at both endpoints involved, and so the state model for an endpoint
+ * includes not only the known local state, but also the last known
+ * state of the remote endpoint.
+ *
  * @ingroup connection
  */
 typedef int pn_state_t;
 
-/**
- * Encapsulates the endpoint state associated with an AMQP Connection.
+/** An AMQP Connection object.
+ *
+ * A pn_connection_t object encapsulates all of the endpoint state
+ * associated with an AMQP Connection. A pn_connection_t object
+ * contains zero or more ::pn_session_t objects, which in turn contain
+ * zero or more ::pn_link_t objects. Each ::pn_link_t object contains
+ * an ordered sequence of ::pn_delivery_t objects. A link is either a
+ * @link sender Sender @endlink, or a @link receiver Receiver
+ * @endlink, but never both.
+ *
  * @ingroup connection
  */
 typedef struct pn_connection_t pn_connection_t;
 
-/**
- * Encapsulates the endpoint state associated with an AMQP Session.
+/** An AMQP Session object.
+ *
+ * A pn_session_t object encapsulates all of the endpoint state
+ * associated with an AMQP Session. A pn_session_t object contains
+ * zero or more ::pn_link_t objects.
+ *
  * @ingroup session
  */
 typedef struct pn_session_t pn_session_t;
 
-/**
- * Encapsulates the endpoint state associated with an AMQP Link.
+/** An AMQP Link object.
+ *
+ * A pn_link_t object encapsulates all of the endpoint state
+ * associated with an AMQP Link. A pn_link_t object contains an
+ * ordered sequence of ::pn_delivery_t objects representing in-flight
+ * deliveries. A pn_link_t may be either a @link sender Sender
+ * @endlink, or a @link receiver Receiver @endlink, but never both.
+ *
+ * A pn_link_t object maintains a pointer to the *current* delivery
+ * within the ordered sequence of deliveries contained by the link
+ * (See ::pn_link_current). The *current* delivery is the target of a
+ * number of operations associated with the link, such as sending
+ * (::pn_link_send) and receiving (::pn_link_recv) message data.
+ *
  * @ingroup link
  */
 typedef struct pn_link_t pn_link_t;
 
-/**
- * Encapsulates the endpoint state associated with an AMQP Delivery.
+/** An AMQP Delivery object.
+ *
+ * A pn_delivery_t object encapsulates all of the endpoint state
+ * associated with an AMQP Delivery. Every delivery exists within the
+ * context of a ::pn_link_t object.
+ *
  * @ingroup delivery
  */
 typedef struct pn_delivery_t pn_delivery_t;
 
-/**
- * An event collector.
+/** An event collector.
+ *
+ * A pn_collector_t may be used to register interest in being notified
+ * of various high level events that can occur to the various objects
+ * representing AMQP endpoint state. See ::pn_connection_collect.
+ *
  * @ingroup event
  */
 typedef struct pn_collector_t pn_collector_t;
 
-/**
- * Encapsulates the transport state of all AMQP endpoints associated
- * with a physical network connection.
+/** An AMQP Transport object.
+ *
+ * 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.
+ *
  * @ingroup transport
  */
 



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


Mime
View raw message