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 10:49:21 UTC
svn commit: r1577469 - in /qpid/proton/trunk/proton-c/include/proton:
disposition.h event.h types.h
Author: rhs
Date: Fri Mar 14 09:49:21 2014
New Revision: 1577469
URL: http://svn.apache.org/r1577469
Log:
doxygen for event.h
Modified:
qpid/proton/trunk/proton-c/include/proton/disposition.h
qpid/proton/trunk/proton-c/include/proton/event.h
qpid/proton/trunk/proton-c/include/proton/types.h
Modified: qpid/proton/trunk/proton-c/include/proton/disposition.h
URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-c/include/proton/disposition.h?rev=1577469&r1=1577468&r2=1577469&view=diff
==============================================================================
--- qpid/proton/trunk/proton-c/include/proton/disposition.h (original)
+++ qpid/proton/trunk/proton-c/include/proton/disposition.h Fri Mar 14 09:49:21 2014
@@ -96,11 +96,11 @@ typedef struct pn_disposition_t pn_dispo
*
* Defined values are:
*
- * - PN_RECEIVED
- * - PN_ACCEPTED
- * - PN_REJECTED
- * - PN_RELEASED
- * - PN_MODIFIED
+ * - ::PN_RECEIVED
+ * - ::PN_ACCEPTED
+ * - ::PN_REJECTED
+ * - ::PN_RELEASED
+ * - ::PN_MODIFIED
*
* @param[in] disposition a disposition object
* @return the type of the disposition
Modified: qpid/proton/trunk/proton-c/include/proton/event.h
URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-c/include/proton/event.h?rev=1577469&r1=1577468&r2=1577469&view=diff
==============================================================================
--- qpid/proton/trunk/proton-c/include/proton/event.h (original)
+++ qpid/proton/trunk/proton-c/include/proton/event.h Fri Mar 14 09:49:21 2014
@@ -33,7 +33,9 @@
extern "C" {
#endif
-/** @file
+/**
+ * @file
+ *
* Event API for the proton Engine.
*
* @defgroup event Event
@@ -42,7 +44,37 @@ extern "C" {
*/
/**
- * An event.
+ * An event provides notification of a state change within the
+ * protocol engine's object model.
+ *
+ * The AMQP endpoint state modeled by the protocol engine is captured
+ * by the following object types: @link pn_delivery_t Deliveries
+ * @endlink, @link pn_link_t Links @endlink, @link pn_session_t
+ * Sessions @endlink, @link pn_connection_t Connections @endlink, and
+ * @link pn_transport_t Transports @endlink. These objects are related
+ * as follows:
+ *
+ * - @link pn_delivery_t Deliveries @endlink always have a single
+ * parent Link
+ * - @link pn_link_t Links @endlink always have a single parent
+ * Session
+ * - @link pn_session_t Sessions @endlink always have a single parent
+ * Connection
+ * - @link pn_connection_t Connections @endlink optionally have at
+ * most one associated Transport
+ * - @link pn_transport_t Transports @endlink optionally have at most
+ * one associated Connection
+ *
+ * Every event has a type (see ::pn_event_type_t) that identifies what
+ * sort of state change has occurred along with a pointer to the
+ * object whose state has changed (as well as its associated objects).
+ *
+ * Events are accessed by creating a @link pn_collector_t Collector
+ * @endlink with ::pn_collector() and registering it with the @link
+ * pn_connection_t Connection @endlink of interest through use of
+ * ::pn_connection_collect(). Once a collector has been registered,
+ * ::pn_collector_peek() and ::pn_collector_pop() are used to access
+ * and process events.
*/
typedef struct pn_event_t pn_event_t;
@@ -50,27 +82,141 @@ typedef struct pn_event_t pn_event_t;
* An event type.
*/
typedef enum {
+ /**
+ * Defined as a programming convenience. No event of this type will
+ * ever be generated.
+ */
PN_EVENT_NONE = 0,
+ /**
+ * The endpoint state flags for a connection have changed. Events of
+ * this type point to the relevant connection as well as its
+ * associated transport.
+ */
PN_CONNECTION_STATE = 1,
+ /**
+ * The endpoint state flags for a session have changed. Events of
+ * this type point to the relevant session as well as its associated
+ * connection and transport.
+ */
PN_SESSION_STATE = 2,
+ /**
+ * The endpoint state flags for a link have changed. Events of this
+ * type point to the relevant link as well as its associated
+ * session, connection, and transport.
+ */
PN_LINK_STATE = 4,
+ /**
+ * The flow control state for a link has changed. Events of this
+ * type point to the relevant link along with its associated
+ * session, connection, and transport.
+ */
PN_LINK_FLOW = 8,
+ /**
+ * A delivery has been created or updated. Events of this type point
+ * to the relevant delivery as well as its associated link, session,
+ * connection, and transport.
+ */
PN_DELIVERY = 16,
+ /**
+ * The transport has new data to read and/or write. Events of this
+ * type point to the relevant transport as well as its associated
+ * connection.
+ */
PN_TRANSPORT = 32
} pn_event_type_t;
+/**
+ * Get a human readable name for an event type.
+ *
+ * @param[in] type an event type
+ * @return a human readable name
+ */
PN_EXTERN const char *pn_event_type_name(pn_event_type_t type);
+/**
+ * Construct a collector.
+ *
+ * A collector is used to register interest in events produced by one
+ * or more ::pn_connection_t objects. Collectors are not currently
+ * thread safe, so synchronization must be used if they are to be
+ * shared between multiple connection objects.
+ */
PN_EXTERN pn_collector_t *pn_collector(void);
+
+/**
+ * Free a collector.
+ *
+ * @param[in] collector a collector to free, or NULL
+ */
PN_EXTERN void pn_collector_free(pn_collector_t *collector);
+
+/**
+ * Access the head event contained by a collector.
+ *
+ * This operation will continue to return the same event until it is
+ * cleared by using ::pn_collector_pop. The pointer return by this
+ * operation will be valid until ::pn_collector_pop is invoked or
+ * ::pn_collector_free is called, whichever happens sooner.
+ *
+ * @param[in] collector a collector object
+ * @return a pointer to the head event contained in the collector
+ */
PN_EXTERN pn_event_t *pn_collector_peek(pn_collector_t *collector);
+
+/**
+ * Clear the head event on a collector.
+ *
+ * @param[in] collector a collector object
+ * @return true if the event was popped, false if the collector is empty
+ */
PN_EXTERN bool pn_collector_pop(pn_collector_t *collector);
+/**
+ * Get the type of an event.
+ *
+ * @param[in] event an event object
+ * @return the type of the event
+ */
PN_EXTERN pn_event_type_t pn_event_type(pn_event_t *event);
+
+/**
+ * Get the connection associated with an event.
+ *
+ * @param[in] event an event object
+ * @return the connection associated with the event (or NULL)
+ */
PN_EXTERN pn_connection_t *pn_event_connection(pn_event_t *event);
+
+/**
+ * Get the session associated with an event.
+ *
+ * @param[in] event an event object
+ * @return the session associated with the event (or NULL)
+ */
PN_EXTERN pn_session_t *pn_event_session(pn_event_t *event);
+
+/**
+ * Get the link associated with an event.
+ *
+ * @param[in] event an event object
+ * @return the link associated with the event (or NULL)
+ */
PN_EXTERN pn_link_t *pn_event_link(pn_event_t *event);
+
+/**
+ * Get the delivery associated with an event.
+ *
+ * @param[in] event an event object
+ * @return the delivery associated with the event (or NULL)
+ */
PN_EXTERN pn_delivery_t *pn_event_delivery(pn_event_t *event);
+
+/**
+ * Get the transport associated with an event.
+ *
+ * @param[in] event an event object
+ * @return the transport associated with the event (or NULL)
+ */
PN_EXTERN pn_transport_t *pn_event_transport(pn_event_t *event);
#ifdef __cplusplus
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=1577469&r1=1577468&r2=1577469&view=diff
==============================================================================
--- qpid/proton/trunk/proton-c/include/proton/types.h (original)
+++ qpid/proton/trunk/proton-c/include/proton/types.h Fri Mar 14 09:49:21 2014
@@ -76,7 +76,8 @@ PN_EXTERN pn_bytes_t pn_bytes_dup(size_t
* @{
*/
-/** Holds the state flags for an AMQP 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
@@ -99,7 +100,8 @@ PN_EXTERN pn_bytes_t pn_bytes_dup(size_t
*/
typedef int pn_state_t;
-/** An AMQP Connection object.
+/**
+ * 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
@@ -113,7 +115,8 @@ typedef int pn_state_t;
*/
typedef struct pn_connection_t pn_connection_t;
-/** An AMQP Session object.
+/**
+ * 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
@@ -123,7 +126,8 @@ typedef struct pn_connection_t pn_connec
*/
typedef struct pn_session_t pn_session_t;
-/** An AMQP Link object.
+/**
+ * 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
@@ -141,7 +145,8 @@ typedef struct pn_session_t pn_session_t
*/
typedef struct pn_link_t pn_link_t;
-/** An AMQP Delivery object.
+/**
+ * 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
@@ -151,17 +156,20 @@ typedef struct pn_link_t pn_link_t;
*/
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.
+ * of high level events that can occur to the various objects
+ * representing AMQP endpoint state. See ::pn_event_t for more
+ * details.
*
* @ingroup event
*/
typedef struct pn_collector_t pn_collector_t;
-/** An AMQP Transport object.
+/**
+ * An AMQP Transport object.
*
* A pn_transport_t encapsulates the transport related state of all
* AMQP endpoint objects associated with a physical network connection
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org