Merge 0.9.12-incubating changes back to master.

src/pulse/pulse.c

@@ -58,6 +58,20 @@ static int guac_pa_is_silence(const void* buffer, size_t length) {
 
 }
 
+/**
+ * Callback invoked by PulseAudio when PCM data is available for reading
+ * from the given stream. The PCM data can be read using pa_stream_peek().
+ *
+ * @param stream
+ *     The PulseAudio stream which has PCM data available.
+ *
+ * @param length
+ *     The number of bytes of PCM data available on the given stream.
+ *
+ * @param data
+ *     A pointer to the guac_pa_stream structure associated with the Guacamole
+ *     stream receiving audio data from PulseAudio.
+ */
 static void __stream_read_callback(pa_stream* stream, size_t length,
         void* data) {
 
@@ -82,6 +96,17 @@ static void __stream_read_callback(pa_stream* stream, size_t length,
 
 }
 
+/**
+ * Callback invoked by PulseAudio when the audio stream has changed state. The
+ * new state can be retrieved using pa_stream_get_state().
+ *
+ * @param stream
+ *     The PulseAudio stream which has changed state.
+ *
+ * @param data
+ *     A pointer to the guac_pa_stream structure associated with the Guacamole
+ *     stream receiving audio data from PulseAudio.
+ */
 static void __stream_state_callback(pa_stream* stream, void* data) {
 
     guac_pa_stream* guac_stream = (guac_pa_stream*) data;
@@ -119,10 +144,34 @@ static void __stream_state_callback(pa_stream* stream, void* data) {
 
 }
 
+/**
+ * Callback invoked by PulseAudio when the audio sink information has been
+ * retrieved. The callback is invoked repeatedly, once for each available
+ * sink, followed by one final invocation with the is_last flag set. The final
+ * invocation (with is_last set) does not describe a sink; it serves as a
+ * terminator only.
+ *
+ * @param context 
+ *     The PulseAudio context which is providing the sink information.
+ *
+ * @param info
+ *     Information describing an available audio sink.
+ *
+ * @param is_last
+ *     Non-zero if this invocation is the final invocation of this callback for
+ *     all currently-available sinks (and this invocation does not describe a
+ *     sink), zero otherwise.
+ *
+ * @param data
+ *     A pointer to the guac_pa_stream structure associated with the Guacamole
+ *     stream receiving audio data from PulseAudio.
+ */
 static void __context_get_sink_info_callback(pa_context* context,
         const pa_sink_info* info, int is_last, void* data) {
 
-    guac_client* client = (guac_client*) data;
+    guac_pa_stream* guac_stream = (guac_pa_stream*) data;
+    guac_client* client = guac_stream->client;
+
     pa_stream* stream;
     pa_sample_spec spec;
     pa_buffer_attr attr;
@@ -146,8 +195,8 @@ static void __context_get_sink_info_callback(pa_context* context,
     stream = pa_stream_new(context, "Guacamole Audio", &spec, NULL);
 
     /* Set stream callbacks */
-    pa_stream_set_state_callback(stream, __stream_state_callback, client);
+    pa_stream_set_state_callback(stream, __stream_state_callback, guac_stream);
-    pa_stream_set_read_callback(stream, __stream_read_callback, client);
+    pa_stream_set_read_callback(stream, __stream_read_callback, guac_stream);
 
     /* Start stream */
     pa_stream_connect_record(stream, info->monitor_source_name, &attr,
@@ -156,10 +205,24 @@ static void __context_get_sink_info_callback(pa_context* context,
 
 }
 
+/**
+ * Callback invoked by PulseAudio when server information has been retrieved.
+ *
+ * @param context 
+ *     The PulseAudio context which is providing the sink information.
+ *
+ * @param info
+ *     Information describing the PulseAudio server.
+ *
+ * @param data
+ *     A pointer to the guac_pa_stream structure associated with the Guacamole
+ *     stream receiving audio data from PulseAudio.
+ */
 static void __context_get_server_info_callback(pa_context* context,
         const pa_server_info* info, void* data) {
 
-    guac_client* client = (guac_client*) data;
+    guac_pa_stream* guac_stream = (guac_pa_stream*) data;
+    guac_client* client = guac_stream->client;
 
     /* If no default sink, cannot continue */
     if (info->default_sink_name == NULL) {
@@ -174,13 +237,25 @@ static void __context_get_server_info_callback(pa_context* context,
     pa_operation_unref(
             pa_context_get_sink_info_by_name(context,
                 info->default_sink_name, __context_get_sink_info_callback,
-                client));
+                guac_stream));
 
 }
 
+/**
+ * Callback invoked by PulseAudio when the overall audio context has changed
+ * state. The new state can be retrieved using pa_context_get_state().
+ *
+ * @param context 
+ *     The PulseAudio context which has changed state.
+ *
+ * @param data
+ *     A pointer to the guac_pa_stream structure associated with the Guacamole
+ *     stream receiving audio data from PulseAudio.
+ */
 static void __context_state_callback(pa_context* context, void* data) {
 
-    guac_client* client = (guac_client*) data;
+    guac_pa_stream* guac_stream = (guac_pa_stream*) data;
+    guac_client* client = guac_stream->client;
 
     switch (pa_context_get_state(context)) {
 
@@ -205,7 +280,7 @@ static void __context_state_callback(pa_context* context, void* data) {
         case PA_CONTEXT_READY:
             guac_client_log(client, GUAC_LOG_INFO, "PulseAudio now ready");
             pa_operation_unref(pa_context_get_server_info(context,
-                        __context_get_server_info_callback, client));
+                        __context_get_server_info_callback, guac_stream));
             break;
 
         case PA_CONTEXT_FAILED: