From: Tanu Kaskinen <tanuk@iki.fi>
Date: Sat, 12 Jan 2013 16:35:41 +0000 (+0200)
Subject: pulse: Document the operation state behavior on context disconnection.
X-Git-Tag: v3.99.1~54
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=7e1ebf9455cc989059ed853413f29e639c7c594c;p=platform%2Fupstream%2Fpulseaudio.git

pulse: Document the operation state behavior on context disconnection.
---

diff --git a/src/pulse/def.h b/src/pulse/def.h
index f8c2a5f..495302f 100644
--- a/src/pulse/def.h
+++ b/src/pulse/def.h
@@ -93,9 +93,14 @@ static inline int PA_STREAM_IS_GOOD(pa_stream_state_t x) {
 
 /** The state of an operation */
 typedef enum pa_operation_state {
-    PA_OPERATION_RUNNING,      /**< The operation is still running */
-    PA_OPERATION_DONE,         /**< The operation has been completed */
-    PA_OPERATION_CANCELLED     /**< The operation has been cancelled. Before 0.9.18 this was called PA_OPERATION_CANCELED. That name is still available for compatibility. */
+    PA_OPERATION_RUNNING,
+    /**< The operation is still running */
+    PA_OPERATION_DONE,
+    /**< The operation has been completed */
+    PA_OPERATION_CANCELLED
+    /**< The operation has been cancelled. Operations may get cancelled by the
+     * application, or as a result of the context getting disconneted while the
+     * operation is pending. */
 } pa_operation_state_t;
 
 /** \cond fulldocs */
diff --git a/src/pulse/operation.h b/src/pulse/operation.h
index 4d5aa2b..82e97c9 100644
--- a/src/pulse/operation.h
+++ b/src/pulse/operation.h
@@ -53,8 +53,12 @@ void pa_operation_cancel(pa_operation *o);
 /** Return the current status of the operation */
 pa_operation_state_t pa_operation_get_state(pa_operation *o);
 
-/** Set the callback function that is called when the operation
- * is canceled due to disconnection. \since 4.0 */
+/** Set the callback function that is called when the operation state
+ * changes. Usually this is not necessary, since the functions that
+ * create pa_operation objects already take a callback that is called
+ * when the operation finishes. Registering a state change callback is
+ * mainly useful, if you want to get called back also if the operation
+ * gets cancelled. \since 4.0 */
 void pa_operation_set_state_callback(pa_operation *o, pa_operation_notify_cb_t cb, void *userdata);
 
 PA_C_DECL_END