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/13 19:59:08 UTC
svn commit: r1577285 -
/qpid/proton/trunk/proton-c/include/proton/disposition.h
Author: rhs
Date: Thu Mar 13 18:59:07 2014
New Revision: 1577285
URL: http://svn.apache.org/r1577285
Log:
doxygen for disposition.h
Modified:
qpid/proton/trunk/proton-c/include/proton/disposition.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=1577285&r1=1577284&r2=1577285&view=diff
==============================================================================
--- qpid/proton/trunk/proton-c/include/proton/disposition.h (original)
+++ qpid/proton/trunk/proton-c/include/proton/disposition.h Thu Mar 13 18:59:07 2014
@@ -33,7 +33,9 @@
extern "C" {
#endif
-/** @file
+/**
+ * @file
+ *
* Disposition API for the proton Engine.
*
* @defgroup disposition Disposition
@@ -41,31 +43,184 @@ extern "C" {
* @{
*/
+/**
+ * Dispositions record the current state and/or final outcome of a
+ * transfer. Every delivery contains both a local and remote
+ * disposition. The local disposition holds the local state of the
+ * delivery, and the remote disposition holds the last known remote
+ * state of the delivery.
+ */
typedef struct pn_disposition_t pn_disposition_t;
/**
- * The state/outcome of a message transfer.
- *
- * @todo document each value
+ * The PN_RECEIVED delivery state is a non terminal state indicating
+ * how much (if any) message data has been received for a delivery.
*/
-
#define PN_RECEIVED (0x0000000000000023)
+
+/**
+ * The PN_ACCEPTED delivery state is a terminal state indicating that
+ * the delivery was successfully processed. Once in this state there
+ * will be no further state changes prior to the delivery being
+ * settled.
+ */
#define PN_ACCEPTED (0x0000000000000024)
+
+/**
+ * The PN_REJECTED delivery state is a terminal state indicating that
+ * the delivery could not be processed due to some error condition.
+ * Once in this state there will be no further state changes prior to
+ * the delivery being settled.
+ */
#define PN_REJECTED (0x0000000000000025)
+
+/**
+ * The PN_RELEASED delivery state is a terminal state indicating that
+ * the delivery is being returned to the sender. Once in this state
+ * there will be no further state changes prior to the delivery being
+ * settled.
+ */
#define PN_RELEASED (0x0000000000000026)
+
+/**
+ * The PN_MODIFIED delivery state is a terminal state indicating that
+ * the delivery is being returned to the sender and should be
+ * annotated by the sender prior to further delivery attempts. Once in
+ * this state there will be no further state changes prior to the
+ * delivery being settled.
+ */
#define PN_MODIFIED (0x0000000000000027)
+/**
+ * Get the type of a disposition.
+ *
+ * Defined values are:
+ *
+ * - PN_RECEIVED
+ * - PN_ACCEPTED
+ * - PN_REJECTED
+ * - PN_RELEASED
+ * - PN_MODIFIED
+ *
+ * @param[in] disposition a disposition object
+ * @return the type of the disposition
+ */
PN_EXTERN uint64_t pn_disposition_type(pn_disposition_t *disposition);
+
+/**
+ * Access the condition object associated with a disposition.
+ *
+ * The ::pn_condition_t object retrieved by this operation may be
+ * modified prior to updating a delivery. When a delivery is updated,
+ * the condition described by the disposition is reported to the peer
+ * if applicable to the current delivery state, e.g. states such as
+ * ::PN_REJECTED.
+ *
+ * The pointer returned by this operation is valid until the parent
+ * delivery is settled.
+ *
+ * @param[in] disposition a disposition object
+ * @return a pointer to the disposition condition
+ */
PN_EXTERN pn_condition_t *pn_disposition_condition(pn_disposition_t *disposition);
+
+/**
+ * Access the disposition as a raw pn_data_t.
+ *
+ * Dispositions are an extension point in the AMQP protocol. The
+ * disposition interface provides setters/getters for those
+ * dispositions that are predefined by the specification, however
+ * access to the raw disposition data is provided so that other
+ * dispositions can be used.
+ *
+ * The ::pn_data_t pointer returned by this operation is valid until
+ * the parent delivery is settled.
+ *
+ * @param[in] disposition a disposition object
+ * @return a pointer to the raw disposition data
+ */
PN_EXTERN pn_data_t *pn_disposition_data(pn_disposition_t *disposition);
+
+/**
+ * Get the section number associated with a disposition.
+ *
+ * @param[in] disposition a disposition object
+ * @return a section number
+ */
PN_EXTERN uint32_t pn_disposition_get_section_number(pn_disposition_t *disposition);
+
+/**
+ * Set the section number associated with a disposition.
+ *
+ * @param[in] disposition a disposition object
+ * @param[in] section_number a section number
+ */
PN_EXTERN void pn_disposition_set_section_number(pn_disposition_t *disposition, uint32_t section_number);
+
+/**
+ * Get the section offset associated with a disposition.
+ *
+ * @param[in] disposition a disposition object
+ * @return a section offset
+ */
PN_EXTERN uint64_t pn_disposition_get_section_offset(pn_disposition_t *disposition);
+
+/**
+ * Set the section offset associated with a disposition.
+ *
+ * @param[in] disposition a disposition object
+ * @param[in] section_offset a section offset
+ */
PN_EXTERN void pn_disposition_set_section_offset(pn_disposition_t *disposition, uint64_t section_offset);
+
+/**
+ * Check if a disposition has the failed flag set.
+ *
+ * @param[in] disposition a disposition object
+ * @return true if the disposition has the failed flag set, false otherwise
+ */
PN_EXTERN bool pn_disposition_is_failed(pn_disposition_t *disposition);
+
+/**
+ * Set the failed flag on a disposition.
+ *
+ * @param[in] disposition a disposition object
+ * @param[in] failed the value of the failed flag
+ */
PN_EXTERN void pn_disposition_set_failed(pn_disposition_t *disposition, bool failed);
+
+/**
+ * Check if a disposition has the undeliverable flag set.
+ *
+ * @param[in] disposition a disposition object
+ * @return true if the disposition has the undeliverable flag set, false otherwise
+ */
PN_EXTERN bool pn_disposition_is_undeliverable(pn_disposition_t *disposition);
+
+/**
+ * Set the undeliverable flag on a disposition.
+ *
+ * @param[in] disposition a disposition object
+ * @param[in] undeliverable the value of the undeliverable flag
+ */
PN_EXTERN void pn_disposition_set_undeliverable(pn_disposition_t *disposition, bool undeliverable);
+
+/**
+ * Access the annotations associated with a disposition.
+ *
+ * The ::pn_data_t object retrieved by this operation may be modified
+ * prior to updating a delivery. When a delivery is updated, the
+ * annotations described by the ::pn_data_t are reported to the peer
+ * if applicable to the current delivery state, e.g. states such as
+ * ::PN_MODIFIED. The ::pn_data_t must be empty or contain a symbol
+ * keyed map.
+ *
+ * The pointer returned by this operation is valid until the parent
+ * delivery is settled.
+ *
+ * @param[in] disposition a disposition object
+ * @return the annotations associated with the disposition
+ */
PN_EXTERN pn_data_t *pn_disposition_annotations(pn_disposition_t *disposition);
/** @}
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org