* a lot of doxygen updates

* s/pa_operation_callback/pa_operation_callback_t/g
* add more typedefs for function prototypes
* add API to query the channel map used by a pa_stream


git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@530 fefdeb5f-60dc-0310-8127-8f9354f1896f

18 files changed, 125 insertions, 100 deletions

diff --git a/src/polyp/channelmap.h b/src/polyp/channelmap.h
index ae1d11c8..dd508abe 100644
--- a/src/polyp/channelmap.h
+++ b/src/polyp/channelmap.h
@@ -105,7 +105,7 @@ const char* pa_channel_position_to_string(pa_channel_position_t pos);
 /** Make a humand readable string from the specified channel map */
 char* pa_channel_map_snprint(char *s, size_t l, const pa_channel_map *map);
 
-/** Compare two channel maps. Return 0 if both match. */
+/** Compare two channel maps. Return 1 if both match. */
 int pa_channel_map_equal(const pa_channel_map *a, const pa_channel_map *b);
 
 /** Return non-zero of the specified channel map is considered valid */
diff --git a/src/polyp/context.c b/src/polyp/context.c
index b174b505..00c09710 100644
--- a/src/polyp/context.c
+++ b/src/polyp/context.c
@@ -742,7 +742,7 @@ pa_operation* pa_context_drain(pa_context *c, pa_context_notify_cb_t cb, void *u
 
     o = pa_operation_new(c, NULL);
     assert(o);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     set_dispatch_callbacks(pa_operation_ref(o));
@@ -812,7 +812,7 @@ pa_operation* pa_context_set_default_sink(pa_context *c, const char *name, pa_co
     assert(c && cb);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -832,7 +832,7 @@ pa_operation* pa_context_set_default_source(pa_context *c, const char *name, pa_
     assert(c && cb);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -857,7 +857,7 @@ pa_operation* pa_context_set_name(pa_context *c, const char *name, pa_context_su
     assert(c && name && cb);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
diff --git a/src/polyp/glib-mainloop.h b/src/polyp/glib-mainloop.h
index e052cff3..b7717685 100644
--- a/src/polyp/glib-mainloop.h
+++ b/src/polyp/glib-mainloop.h
@@ -32,18 +32,18 @@
 
 PA_C_DECL_BEGIN
 
-/** \struct pa_glib_mainloop
- * An opaque GLIB main loop object */
+/** An opaque GLIB main loop object */
 typedef struct pa_glib_mainloop pa_glib_mainloop;
 
-/** Create a new GLIB main loop object for the specified GLIB main loop context. If c is NULL the default context is used. */
+/** Create a new GLIB main loop object for the specified GLIB main
+ * loop context. The GLIB 2.0 version takes an argument c for the
+ * GMainContext to use. If c is NULL the default context is used. */
 #if GLIB_MAJOR_VERSION >= 2
 pa_glib_mainloop *pa_glib_mainloop_new(GMainContext *c);
 #else
 pa_glib_mainloop *pa_glib_mainloop_new(void);
 #endif
 
-
 /** Free the GLIB main loop object */
 void pa_glib_mainloop_free(pa_glib_mainloop* g);
 
diff --git a/src/polyp/internal.h b/src/polyp/internal.h
index f0374b67..e9e0246f 100644
--- a/src/polyp/internal.h
+++ b/src/polyp/internal.h
@@ -26,6 +26,7 @@
 #include <polyp/context.h>
 #include <polyp/stream.h>
 #include <polyp/operation.h>
+#include <polyp/subscribe.h>
 
 #include <polypcore/socket-client.h>
 #include <polypcore/pstream.h>
@@ -63,7 +64,7 @@ struct pa_context {
     pa_context_notify_cb_t state_callback;
     void *state_userdata;
 
-    void (*subscribe_callback)(pa_context *c, pa_subscription_event_type_t t, uint32_t idx, void *userdata);
+    pa_context_subscribe_cb_t subscribe_callback;
     void *subscribe_userdata;
 
     pa_memblock_stat *memblock_stat;
@@ -127,7 +128,7 @@ struct pa_stream {
     void *underflow_userdata;
 };
 
-typedef void (*pa_operation_callback)(void);
+typedef void (*pa_operation_callback_t)(void);
 
 struct pa_operation {
     int ref;
@@ -137,7 +138,7 @@ struct pa_operation {
 
     pa_operation_state_t state;
     void *userdata;
-    pa_operation_callback callback;
+    pa_operation_callback_t callback;
 };
 
 void pa_command_request(pa_pdispatch *pd, uint32_t command, uint32_t tag, pa_tagstruct *t, void *userdata);
diff --git a/src/polyp/introspect.c b/src/polyp/introspect.c
index 75ce3ff9..404cead5 100644
--- a/src/polyp/introspect.c
+++ b/src/polyp/introspect.c
@@ -67,7 +67,7 @@ finish:
 }
 
 pa_operation* pa_context_stat(pa_context *c, void (*cb)(pa_context *c, const pa_stat_info*i, void *userdata), void *userdata) {
-    return pa_context_send_simple_command(c, PA_COMMAND_STAT, context_stat_callback, (pa_operation_callback) cb, userdata);
+    return pa_context_send_simple_command(c, PA_COMMAND_STAT, context_stat_callback, (pa_operation_callback_t) cb, userdata);
 }
 
 /*** Server Info ***/
@@ -107,7 +107,7 @@ finish:
 }
 
 pa_operation* pa_context_get_server_info(pa_context *c, void (*cb)(pa_context *c, const pa_server_info*i, void *userdata), void *userdata) {
-    return pa_context_send_simple_command(c, PA_COMMAND_GET_SERVER_INFO, context_get_server_info_callback, (pa_operation_callback) cb, userdata);
+    return pa_context_send_simple_command(c, PA_COMMAND_GET_SERVER_INFO, context_get_server_info_callback, (pa_operation_callback_t) cb, userdata);
 }
 
 /*** Sink Info ***/
@@ -161,7 +161,7 @@ finish:
 }
 
 pa_operation* pa_context_get_sink_info_list(pa_context *c, void (*cb)(pa_context *c, const pa_sink_info *i, int is_last, void *userdata), void *userdata) {
-    return pa_context_send_simple_command(c, PA_COMMAND_GET_SINK_INFO_LIST, context_get_sink_info_callback, (pa_operation_callback) cb, userdata);
+    return pa_context_send_simple_command(c, PA_COMMAND_GET_SINK_INFO_LIST, context_get_sink_info_callback, (pa_operation_callback_t) cb, userdata);
 }
 
 pa_operation* pa_context_get_sink_info_by_index(pa_context *c, uint32_t idx, void (*cb)(pa_context *c, const pa_sink_info *i, int is_last, void *userdata), void *userdata) {
@@ -171,7 +171,7 @@ pa_operation* pa_context_get_sink_info_by_index(pa_context *c, uint32_t idx, voi
     assert(c && cb);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -192,7 +192,7 @@ pa_operation* pa_context_get_sink_info_by_name(pa_context *c, const char *name,
     assert(c && cb);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -256,7 +256,7 @@ finish:
 }
 
 pa_operation* pa_context_get_source_info_list(pa_context *c, void (*cb)(pa_context *c, const pa_source_info *i, int is_last, void *userdata), void *userdata) {
-    return pa_context_send_simple_command(c, PA_COMMAND_GET_SOURCE_INFO_LIST, context_get_source_info_callback, (pa_operation_callback) cb, userdata);
+    return pa_context_send_simple_command(c, PA_COMMAND_GET_SOURCE_INFO_LIST, context_get_source_info_callback, (pa_operation_callback_t) cb, userdata);
 }
 
 pa_operation* pa_context_get_source_info_by_index(pa_context *c, uint32_t idx, void (*cb)(pa_context *c, const pa_source_info *i, int is_last, void *userdata), void *userdata) {
@@ -266,7 +266,7 @@ pa_operation* pa_context_get_source_info_by_index(pa_context *c, uint32_t idx, v
     assert(c && cb);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -287,7 +287,7 @@ pa_operation* pa_context_get_source_info_by_name(pa_context *c, const char *name
     assert(c && cb);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -350,7 +350,7 @@ pa_operation* pa_context_get_client_info(pa_context *c, uint32_t idx, void (*cb)
     assert(c && cb);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -364,7 +364,7 @@ pa_operation* pa_context_get_client_info(pa_context *c, uint32_t idx, void (*cb)
 }
 
 pa_operation* pa_context_get_client_info_list(pa_context *c, void (*cb)(pa_context *c, const pa_client_info*i, int is_last, void *userdata), void *userdata) {
-    return pa_context_send_simple_command(c, PA_COMMAND_GET_CLIENT_INFO_LIST, context_get_client_info_callback, (pa_operation_callback) cb, userdata);
+    return pa_context_send_simple_command(c, PA_COMMAND_GET_CLIENT_INFO_LIST, context_get_client_info_callback, (pa_operation_callback_t) cb, userdata);
 }
 
 /*** Module info ***/
@@ -417,7 +417,7 @@ pa_operation* pa_context_get_module_info(pa_context *c, uint32_t idx, void (*cb)
     assert(c && cb);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -431,7 +431,7 @@ pa_operation* pa_context_get_module_info(pa_context *c, uint32_t idx, void (*cb)
 }
 
 pa_operation* pa_context_get_module_info_list(pa_context *c, void (*cb)(pa_context *c, const pa_module_info*i, int is_last, void *userdata), void *userdata) {
-    return pa_context_send_simple_command(c, PA_COMMAND_GET_MODULE_INFO_LIST, context_get_module_info_callback, (pa_operation_callback) cb, userdata);
+    return pa_context_send_simple_command(c, PA_COMMAND_GET_MODULE_INFO_LIST, context_get_module_info_callback, (pa_operation_callback_t) cb, userdata);
 }
 
 /*** Sink input info ***/
@@ -492,7 +492,7 @@ pa_operation* pa_context_get_sink_input_info(pa_context *c, uint32_t idx, void (
     assert(c && cb);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -506,7 +506,7 @@ pa_operation* pa_context_get_sink_input_info(pa_context *c, uint32_t idx, void (
 }
 
 pa_operation* pa_context_get_sink_input_info_list(pa_context *c, void (*cb)(pa_context *c, const pa_sink_input_info*i, int is_last, void *userdata), void *userdata) {
-    return pa_context_send_simple_command(c, PA_COMMAND_GET_SINK_INPUT_INFO_LIST, context_get_sink_input_info_callback, (pa_operation_callback) cb, userdata);
+    return pa_context_send_simple_command(c, PA_COMMAND_GET_SINK_INPUT_INFO_LIST, context_get_sink_input_info_callback, (pa_operation_callback_t) cb, userdata);
 }
 
 /*** Source output info ***/
@@ -566,7 +566,7 @@ pa_operation* pa_context_get_source_output_info(pa_context *c, uint32_t idx, voi
     assert(c && cb);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -580,7 +580,7 @@ pa_operation* pa_context_get_source_output_info(pa_context *c, uint32_t idx, voi
 }
 
 pa_operation* pa_context_get_source_output_info_list(pa_context *c, void (*cb)(pa_context *c, const pa_source_output_info*i, int is_last, void *userdata), void *userdata) {
-    return pa_context_send_simple_command(c, PA_COMMAND_GET_SOURCE_OUTPUT_INFO_LIST, context_get_source_output_info_callback, (pa_operation_callback) cb, userdata);
+    return pa_context_send_simple_command(c, PA_COMMAND_GET_SOURCE_OUTPUT_INFO_LIST, context_get_source_output_info_callback, (pa_operation_callback_t) cb, userdata);
 }
 
 /*** Volume manipulation ***/
@@ -592,7 +592,7 @@ pa_operation* pa_context_set_sink_volume_by_index(pa_context *c, uint32_t idx, c
     assert(c && idx != PA_INVALID_INDEX);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -614,7 +614,7 @@ pa_operation* pa_context_set_sink_volume_by_name(pa_context *c, const char *name
     assert(c && name);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -636,7 +636,7 @@ pa_operation* pa_context_set_sink_input_volume(pa_context *c, uint32_t idx, cons
     assert(c && idx != PA_INVALID_INDEX);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -705,7 +705,7 @@ pa_operation* pa_context_get_sample_info_by_name(pa_context *c, const char *name
     assert(c && cb && name);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -726,7 +726,7 @@ pa_operation* pa_context_get_sample_info_by_index(pa_context *c, uint32_t idx, v
     assert(c && cb);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -741,7 +741,7 @@ pa_operation* pa_context_get_sample_info_by_index(pa_context *c, uint32_t idx, v
 }
 
 pa_operation* pa_context_get_sample_info_list(pa_context *c, void (*cb)(pa_context *c, const pa_sample_info *i, int is_last, void *userdata), void *userdata) {
-    return pa_context_send_simple_command(c, PA_COMMAND_GET_SAMPLE_INFO_LIST, context_get_sample_info_callback, (pa_operation_callback) cb, userdata);
+    return pa_context_send_simple_command(c, PA_COMMAND_GET_SAMPLE_INFO_LIST, context_get_sample_info_callback, (pa_operation_callback_t) cb, userdata);
 }
 
 static pa_operation* command_kill(pa_context *c, uint32_t command, uint32_t idx, void (*cb)(pa_context *c, int success, void *userdata), void *userdata) {
@@ -751,7 +751,7 @@ static pa_operation* command_kill(pa_context *c, uint32_t command, uint32_t idx,
     assert(c && idx != PA_INVALID_INDEX);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -808,7 +808,7 @@ pa_operation* pa_context_load_module(pa_context *c, const char*name, const char
     assert(c && name && argument);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -876,7 +876,7 @@ pa_operation* pa_context_get_autoload_info_by_name(pa_context *c, const char *na
     assert(c && cb && name);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -897,7 +897,7 @@ pa_operation* pa_context_get_autoload_info_by_index(pa_context *c, uint32_t idx,
     assert(c && cb && idx != PA_INVALID_INDEX);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -911,7 +911,7 @@ pa_operation* pa_context_get_autoload_info_by_index(pa_context *c, uint32_t idx,
 }
 
 pa_operation* pa_context_get_autoload_info_list(pa_context *c, void (*cb)(pa_context *c, const pa_autoload_info *i, int is_last, void *userdata), void *userdata) {
-    return pa_context_send_simple_command(c, PA_COMMAND_GET_AUTOLOAD_INFO_LIST, context_get_autoload_info_callback, (pa_operation_callback) cb, userdata);
+    return pa_context_send_simple_command(c, PA_COMMAND_GET_AUTOLOAD_INFO_LIST, context_get_autoload_info_callback, (pa_operation_callback_t) cb, userdata);
 }
 
 static void context_add_autoload_callback(pa_pdispatch *pd, uint32_t command, PA_GCC_UNUSED uint32_t tag, pa_tagstruct *t, void *userdata) {
@@ -948,7 +948,7 @@ pa_operation* pa_context_add_autoload(pa_context *c, const char *name, pa_autolo
     assert(c && name && module && argument);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -971,7 +971,7 @@ pa_operation* pa_context_remove_autoload_by_name(pa_context *c, const char *name
     assert(c && name);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -992,7 +992,7 @@ pa_operation* pa_context_remove_autoload_by_index(pa_context *c, uint32_t idx, v
     assert(c && idx != PA_INVALID_INDEX);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
diff --git a/src/polyp/mainloop-api.h b/src/polyp/mainloop-api.h
index 7bc7522c..12d74aa1 100644
--- a/src/polyp/mainloop-api.h
+++ b/src/polyp/mainloop-api.h
@@ -53,21 +53,19 @@ typedef enum pa_io_event_flags {
     PA_IO_EVENT_ERROR = 8     /**< Error event */
 } pa_io_event_flags_t;
 
-/** \struct pa_io_event
- * An opaque IO event source object */
+/** An opaque IO event source object */
 typedef struct pa_io_event pa_io_event;
 
-/** \struct pa_defer_event
- * An opaque deferred event source object. Events of this type are triggered once in every main loop iteration */
+/** An opaque deferred event source object. Events of this type are triggered once in every main loop iteration */
 typedef struct pa_defer_event pa_defer_event;
 
-/** \struct pa_time_event
- * An opaque timer event source object */
+/** An opaque timer event source object */
 typedef struct pa_time_event pa_time_event;
 
 /** An abstract mainloop API vtable */
 typedef struct pa_mainloop_api pa_mainloop_api;
 
+/** An abstract mainloop API vtable */
 struct pa_mainloop_api  {
     /** A pointer to some private, arbitrary data of the main loop implementation */
     void *userdata;
diff --git a/src/polyp/mainloop-signal.h b/src/polyp/mainloop-signal.h
index 0291f426..20e97988 100644
--- a/src/polyp/mainloop-signal.h
+++ b/src/polyp/mainloop-signal.h
@@ -42,8 +42,7 @@ int pa_signal_init(pa_mainloop_api *api);
 /** Cleanup the signal subsystem */
 void pa_signal_done(void);
 
-/** \struct pa_signal_event
- * An opaque UNIX signal event source object */
+/** An opaque UNIX signal event source object */
 typedef struct pa_signal_event pa_signal_event;
 
 /** Create a new UNIX signal event source object */
diff --git a/src/polyp/mainloop.h b/src/polyp/mainloop.h
index eeb23884..d0a40914 100644
--- a/src/polyp/mainloop.h
+++ b/src/polyp/mainloop.h
@@ -35,9 +35,7 @@ PA_C_DECL_BEGIN
  * defined in \ref mainloop-api.h. This implementation is thread safe
  * as long as you access the main loop object from a single thread only.*/
 
-/** \struct pa_mainloop
- * An opaque main loop object
- */
+/** An opaque main loop object */
 typedef struct pa_mainloop pa_mainloop;
 
 /** Allocate a new main loop object */
@@ -52,8 +50,10 @@ poll, or -1 for blocking behaviour. Defer events are also dispatched when this
 function is called. On success returns the number of source dispatched in this
 iteration.*/
 int pa_mainloop_prepare(pa_mainloop *m, int timeout);
+
 /** Execute the previously prepared poll. Returns a negative value on error.*/
 int pa_mainloop_poll(pa_mainloop *m);
+
 /** Dispatch timeout and io events from the previously executed poll. Returns
 a negative value on error. On success returns the number of source dispatched. */
 int pa_mainloop_dispatch(pa_mainloop *m);
diff --git a/src/polyp/operation.h b/src/polyp/operation.h
index d286b0c1..2fbac2e2 100644
--- a/src/polyp/operation.h
+++ b/src/polyp/operation.h
@@ -30,8 +30,7 @@
 
 PA_C_DECL_BEGIN
 
-/** \struct pa_operation
- * An asynchronous operation object */
+/** An asynchronous operation object */
 typedef struct pa_operation pa_operation;
 
 /** Increase the reference count by one */
diff --git a/src/polyp/polypaudio.h b/src/polyp/polypaudio.h
index c81fdfdb..b70b8d70 100644
--- a/src/polyp/polypaudio.h
+++ b/src/polyp/polypaudio.h
@@ -22,7 +22,6 @@
   USA.
 ***/
 
-#include <polyp/cdecl.h>
 #include <polyp/mainloop-api.h>
 #include <polyp/sample.h>
 #include <polyp/def.h>
@@ -33,12 +32,16 @@
 #include <polyp/scache.h>
 #include <polyp/version.h>
 #include <polyp/error.h>
+#include <polyp/operation.h>
+#include <polyp/channelmap.h>
+#include <polyp/volume.h>
 
 /** \file
- * Include all polyplib header file at once. The following files are included: \ref mainloop-api.h, \ref sample.h,
- * \ref def.h, \ref context.h, \ref stream.h,
- * \ref introspect.h, \ref subscribe.h, \ref scache.h, \ref version.h \ref error.h
- * at once */
+ * Include all polyplib header file at once. The following
+ * files are included: \ref mainloop-api.h, \ref sample.h, \ref def.h,
+ * \ref context.h, \ref stream.h, \ref introspect.h, \ref subscribe.h,
+ * \ref scache.h, \ref version.h, \ref error.h, \ref channelmap.h,
+ * \ref operation.h and \ref volume.h at once */
 
 /** \mainpage
  *
diff --git a/src/polyp/sample.h b/src/polyp/sample.h
index c1b98f1c..db4c6c70 100644
--- a/src/polyp/sample.h
+++ b/src/polyp/sample.h
@@ -33,7 +33,7 @@
 
 PA_C_DECL_BEGIN
 
-/* Maximum allowed channels */
+/** Maximum allowed channels */
 #define PA_CHANNELS_MAX 16
 
 /** Sample format */
@@ -43,8 +43,8 @@ typedef enum pa_sample_format {
     PA_SAMPLE_ULAW,            /**< 8 Bit mu-Law */
     PA_SAMPLE_S16LE,           /**< Signed 16 Bit PCM, little endian (PC) */
     PA_SAMPLE_S16BE,           /**< Signed 16 Bit PCM, big endian */
-    PA_SAMPLE_FLOAT32LE,       /**< 32 Bit IEEE floating point, little endian, range -1..1 */
-    PA_SAMPLE_FLOAT32BE,       /**< 32 Bit IEEE floating point, big endian, range -1..1 */
+    PA_SAMPLE_FLOAT32LE,       /**< 32 Bit IEEE floating point, little endian, range -1 to 1 */
+    PA_SAMPLE_FLOAT32BE,       /**< 32 Bit IEEE floating point, big endian, range -1 to 1 */
     PA_SAMPLE_MAX,             /**< Upper limit of valid sample types */
     PA_SAMPLE_INVALID = -1     /**< An invalid value */
 } pa_sample_format_t;
@@ -100,7 +100,7 @@ int pa_sample_spec_valid(const pa_sample_spec *spec);
 /** Return non-zero when the two sample type specifications match */
 int pa_sample_spec_equal(const pa_sample_spec*a, const pa_sample_spec*b);
 
-/* Return a descriptive string for the specified sample format. \since 0.8 */
+/** Return a descriptive string for the specified sample format. \since 0.8 */
 const char *pa_sample_format_to_string(pa_sample_format_t f);
 
 /** Parse a sample format text. Inverse of pa_sample_format_to_string() */
diff --git a/src/polyp/scache.c b/src/polyp/scache.c
index 393b069e..f6a3a7e6 100644
--- a/src/polyp/scache.c
+++ b/src/polyp/scache.c
@@ -79,14 +79,14 @@ void pa_stream_finish_upload(pa_stream *s) {
     pa_stream_unref(s);
 }
 
-pa_operation * pa_context_play_sample(pa_context *c, const char *name, const char *dev, uint32_t volume, void (*cb)(pa_context *c, int success, void *userdata), void *userdata) {
+pa_operation * pa_context_play_sample(pa_context *c, const char *name, const char *dev, uint32_t volume, pa_context_success_cb_t cb, void *userdata) {
     pa_operation *o;
     pa_tagstruct *t;
     uint32_t tag;
     assert(c && name && *name && (!dev || *dev));
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     if (!dev)
@@ -106,14 +106,14 @@ pa_operation * pa_context_play_sample(pa_context *c, const char *name, const cha
     return pa_operation_ref(o);
 }
 
-pa_operation* pa_context_remove_sample(pa_context *c, const char *name, void (*cb)(pa_context *c, int success, void *userdata), void *userdata) {
+pa_operation* pa_context_remove_sample(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata) {
     pa_operation *o;
     pa_tagstruct *t;
     uint32_t tag;
     assert(c && name);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
     
     t = pa_tagstruct_new(NULL, 0);
diff --git a/src/polyp/scache.h b/src/polyp/scache.h
index 5bf004d0..3480d876 100644
--- a/src/polyp/scache.h
+++ b/src/polyp/scache.h
@@ -36,14 +36,21 @@ PA_C_DECL_BEGIN
 /** Make this stream a sample upload stream */
 void pa_stream_connect_upload(pa_stream *s, size_t length);
 
-/** Finish the sample upload, the stream name will become the sample name. You cancel a sample upload by issuing pa_stream_disconnect() */
+/** Finish the sample upload, the stream name will become the sample name. You cancel a samp
+ * le upload by issuing pa_stream_disconnect() */
 void pa_stream_finish_upload(pa_stream *s);
 
 /** Play a sample from the sample cache to the specified device. If the latter is NULL use the default sink. Returns an operation object */
-pa_operation* pa_context_play_sample(pa_context *c, const char *name, const char *dev, uint32_t volume, void (*cb)(pa_context *c, int success, void *userdata), void *userdata);
+pa_operation* pa_context_play_sample(
+        pa_context *c               /**< Context */,
+        const char *name            /**< Name of the sample to play */,
+        const char *dev             /**< Sink to play this sample on */,
+        pa_volume_t volume          /**< Volume to play this sample with */ ,
+        pa_context_success_cb_t cb  /**< Call this function after successfully starting playback, or NULL */,
+        void *userdata              /**< Userdata to pass to the callback */);
 
 /** Remove a sample from the sample cache. Returns an operation object which may be used to cancel the operation while it is running */
-pa_operation* pa_context_remove_sample(pa_context *c, const char *name, void (*cb)(pa_context *c, int success, void *userdata), void *userdata);
+pa_operation* pa_context_remove_sample(pa_context *c, const char *name, pa_context_success_cb_t, void *userdata);
 
 PA_C_DECL_END
 
diff --git a/src/polyp/stream.c b/src/polyp/stream.c
index 5497f0c4..88971085 100644
--- a/src/polyp/stream.c
+++ b/src/polyp/stream.c
@@ -592,7 +592,7 @@ pa_operation * pa_stream_drain(pa_stream *s, void (*cb) (pa_stream*s, int succes
     PA_CHECK_VALIDITY_RETURN_NULL(s->context, s->direction == PA_STREAM_PLAYBACK, PA_ERR_BADSTATE);
 
     o = pa_operation_new(s->context, s);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -680,7 +680,7 @@ pa_operation* pa_stream_get_latency_info(pa_stream *s, void (*cb)(pa_stream *p,
     PA_CHECK_VALIDITY_RETURN_NULL(s->context, s->direction != PA_STREAM_UPLOAD, PA_ERR_BADSTATE);
     
     o = pa_operation_new(s->context, s);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -830,7 +830,7 @@ pa_operation* pa_stream_cork(pa_stream *s, int b, void (*cb) (pa_stream*s, int s
     
     o = pa_operation_new(s->context, s);
     assert(o);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -854,7 +854,7 @@ static pa_operation* stream_send_simple_command(pa_stream *s, uint32_t command,
     assert(s && s->ref >= 1 && s->state == PA_STREAM_READY);
     
     o = pa_operation_new(s->context, s);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -896,7 +896,7 @@ pa_operation* pa_stream_set_name(pa_stream *s, const char *name, void(*cb)(pa_st
 
     o = pa_operation_new(s->context, s);
     assert(o);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -978,9 +978,16 @@ pa_usec_t pa_stream_get_latency(pa_stream *s, const pa_latency_info *i, int *neg
 
 const pa_sample_spec* pa_stream_get_sample_spec(pa_stream *s) {
     assert(s);
+    
     return &s->sample_spec;
 }
 
+const pa_channel_map* pa_stream_get_channel_map(pa_stream *s) {
+    assert(s);
+
+    return &s->channel_map;
+}
+
 void pa_stream_trash_ipol(pa_stream *s) {
     assert(s);
 
diff --git a/src/polyp/stream.h b/src/polyp/stream.h
index ce535963..75b0a900 100644
--- a/src/polyp/stream.h
+++ b/src/polyp/stream.h
@@ -36,8 +36,7 @@
 
 PA_C_DECL_BEGIN
 
-/** \struct pa_stream
- * An opaque stream for playback or recording */
+/** An opaque stream for playback or recording */
 typedef struct pa_stream pa_stream;
 
 /** A generic callback for operation completion */
@@ -57,10 +56,10 @@ typedef void (*pa_stream_get_latency_info_cb_t)(pa_stream *p, const pa_latency_i
 
 /** Create a new, unconnected stream with the specified name and sample type */
 pa_stream* pa_stream_new(
-        pa_context *c,
-        const char *name,
-        const pa_sample_spec *ss,
-        const pa_channel_map *map);
+        pa_context *c                     /**< The context to create this stream in */,             
+        const char *name                  /**< A name for this stream */,
+        const pa_sample_spec *ss          /**< The desired sample format */,
+        const pa_channel_map *map         /**< The desired channel map, or NULL for default */);
 
 /** Decrease the reference counter by one */
 void pa_stream_unref(pa_stream *s);
@@ -88,10 +87,10 @@ int pa_stream_connect_playback(
 
 /** Connect the stream to a source */
 int pa_stream_connect_record(
-        pa_stream *s,
-        const char *dev,
-        const pa_buffer_attr *attr,
-        pa_stream_flags_t flags);
+        pa_stream *s                  /**< The stream to connect to a source */ ,
+        const char *dev               /**< Name of the source to connect to, or NULL for default */,
+        const pa_buffer_attr *attr    /**< Buffer attributes, or NULL for default */,
+        pa_stream_flags_t flags       /**< Additional flags, or 0 for default */);
 
 /** Disconnect a stream from a source/sink */
 int pa_stream_disconnect(pa_stream *s);
@@ -203,9 +202,12 @@ pa_usec_t pa_stream_get_interpolated_time(pa_stream *s);
  * stream. \since 0.6 */
 pa_usec_t pa_stream_get_interpolated_latency(pa_stream *s, int *negative);
 
-/** Return a pointer to the streams sample specification. \since 0.6 */
+/** Return a pointer to the stream's sample specification. \since 0.6 */
 const pa_sample_spec* pa_stream_get_sample_spec(pa_stream *s);
 
+/** Return a pointer to the stream's channel map. \since 0.8 */
+const pa_channel_map* pa_stream_get_channel_map(pa_stream *s);
+
 PA_C_DECL_END
 
 #endif
diff --git a/src/polyp/subscribe.c b/src/polyp/subscribe.c
index 4e00997a..97f76cb7 100644
--- a/src/polyp/subscribe.c
+++ b/src/polyp/subscribe.c
@@ -56,14 +56,14 @@ finish:
 }
 
 
-pa_operation* pa_context_subscribe(pa_context *c, pa_subscription_mask_t m, void (*cb)(pa_context *c, int success, void *userdata), void *userdata) {
+pa_operation* pa_context_subscribe(pa_context *c, pa_subscription_mask_t m, pa_context_success_cb_t cb, void *userdata) {
     pa_operation *o;
     pa_tagstruct *t;
     uint32_t tag;
     assert(c);
 
     o = pa_operation_new(c, NULL);
-    o->callback = (pa_operation_callback) cb;
+    o->callback = (pa_operation_callback_t) cb;
     o->userdata = userdata;
 
     t = pa_tagstruct_new(NULL, 0);
@@ -76,7 +76,7 @@ pa_operation* pa_context_subscribe(pa_context *c, pa_subscription_mask_t m, void
     return pa_operation_ref(o);
 }
 
-void pa_context_set_subscribe_callback(pa_context *c, void (*cb)(pa_context *c, pa_subscription_event_type_t t, uint32_t index, void *userdata), void *userdata) {
+void pa_context_set_subscribe_callback(pa_context *c, pa_context_subscribe_cb_t cb, void *userdata) {
     assert(c);
     c->subscribe_callback = cb;
     c->subscribe_userdata = userdata;
diff --git a/src/polyp/subscribe.h b/src/polyp/subscribe.h
index f1f0642d..5301739a 100644
--- a/src/polyp/subscribe.h
+++ b/src/polyp/subscribe.h
@@ -36,11 +36,14 @@
 
 PA_C_DECL_BEGIN
 
+/** Subscription event callback prototype */
+typedef void (*pa_context_subscribe_cb_t)(pa_context *c, pa_subscription_event_type_t t, uint32_t idx, void *userdata);
+
 /** Enable event notification */
-pa_operation* pa_context_subscribe(pa_context *c, pa_subscription_mask_t m, void (*cb)(pa_context *c, int success, void *userdata), void *userdata);
+pa_operation* pa_context_subscribe(pa_context *c, pa_subscription_mask_t m, pa_context_success_cb_t cb, void *userdata);
 
 /** Set the context specific call back function that is called whenever the state of the daemon changes */
-void pa_context_set_subscribe_callback(pa_context *c, void (*cb)(pa_context *c, pa_subscription_event_type_t t, uint32_t index, void *userdata), void *userdata);
+void pa_context_set_subscribe_callback(pa_context *c, pa_context_subscribe_cb_t cb, void *userdata);
 
 PA_C_DECL_END
 
diff --git a/src/polyp/volume.h b/src/polyp/volume.h
index b2a48084..d1e858c4 100644
--- a/src/polyp/volume.h
+++ b/src/polyp/volume.h
@@ -46,8 +46,8 @@ typedef uint32_t pa_volume_t;
 
 /** A structure encapsulating a per-channel volume */
 typedef struct pa_cvolume {
-    uint8_t channels;
-    pa_volume_t values[PA_CHANNELS_MAX];
+    uint8_t channels;                     /**< Number of channels */
+    pa_volume_t values[PA_CHANNELS_MAX];  /**< Per-channel volume  */
 } pa_cvolume;
 
 /** Return non-zero when *a == *b */
@@ -62,8 +62,10 @@ int pa_cvolume_equal(const pa_cvolume *a, const pa_cvolume *b);
 /** Set the volume of all channels to the specified parameter */
 pa_cvolume* pa_cvolume_set(pa_cvolume *a, unsigned channels, pa_volume_t v);
 
-/** Pretty print a volume structure */
+/** Maximum length of the strings returned by pa_cvolume_snprint() */
 #define PA_CVOLUME_SNPRINT_MAX 64
+
+/** Pretty print a volume structure */
 char *pa_cvolume_snprint(char *s, size_t l, const pa_cvolume *c);
 
 /** Return the average volume of all channels */
@@ -75,24 +77,28 @@ int pa_cvolume_valid(const pa_cvolume *v);
 /** Return non-zero if the volume of all channels is equal to the specified value */
 int pa_cvolume_channels_equal_to(const pa_cvolume *a, pa_volume_t v);
 
+/** Return 1 if the specified volume has all channels muted */
 #define pa_cvolume_is_muted(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_MUTED)
+
+/** Return 1 if the specified volume has all channels on normal level */
 #define pa_cvolume_is_norm(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_NORM)
 
-/** Multiply two volumes specifications, return the result. This uses PA_VOLUME_NORM as neutral element of multiplication. */
+/** Multiply two volumes specifications, return the result. This uses PA_VOLUME_NORM as neutral element of multiplication. This is only valid for software volumes! */
 pa_volume_t pa_sw_volume_multiply(pa_volume_t a, pa_volume_t b);
 
+/** Multiply to per-channel volumes and return the result in *dest. This is only valid for software volumes! */
 pa_cvolume *pa_sw_cvolume_multiply(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
 
-/** Convert a decibel value to a volume. \since 0.4 */
+/** Convert a decibel value to a volume. This is only valid for software volumes! \since 0.4 */
 pa_volume_t pa_sw_volume_from_dB(double f);
 
-/** Convert a volume to a decibel value.  \since 0.4 */
+/** Convert a volume to a decibel value. This is only valid for software volumes! \since 0.4 */
 double pa_sw_volume_to_dB(pa_volume_t v);
 
-/** Convert a linear factor to a volume. \since 0.8 */
+/** Convert a linear factor to a volume. This is only valid for software volumes! \since 0.8 */
 pa_volume_t pa_sw_volume_from_linear(double v);
 
-/** Convert a volume to a linear factor. \since 0.8 */
+/** Convert a volume to a linear factor. This is only valid for software volumes! \since 0.8 */
 double pa_sw_volume_to_linear(pa_volume_t v);
 
 #ifdef INFINITY