[pulseaudio-discuss] [PATCH] pulse: Document the operation state behavior on context disconnection.

[Tanu Kaskinen]

---

Earlier, the operation state behaviour during context disconnection
was not documented. This patch documents that, so we are now tied to
the current behavior forever. I think this is fine, but I'm sending
this patch for review anyway, in case someone thinks that we should
not make that commitment. If there are no objections, I'll commit
this in few days.

 src/pulse/def.h       |   11 ++++++++---
 src/pulse/operation.h |    8 ++++++--
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/src/pulse/def.h b/src/pulse/def.h
index b939319..792fca2 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
-- 
1.7.10.4