Configuration:

  - changed snd_config_get_id function to follow semantic of other get functions
  - added snd_config_test_id
  - added runtime pointer type (not persistent)
    - added snd_config_make_pointer, snd_config_set_pointer, snd_config_get_pointer
  - added type/contents checking for callback functions
    - changed 'void *private_data' to 'snd_config_t *private_data'
  - renamed card_strtype functions to card_driver
Control:
  - fixed passing parameters to snd_ctl_async
Async handlers:
  - added public snd_async_handler_get_signo function
Documentation:
  - moved all documentation to source files

5 files changed, 53 insertions, 39 deletions

diff --git a/include/conf.h b/include/conf.h
index 74cfe113..0fc0636b 100644
--- a/include/conf.h
+++ b/include/conf.h
@@ -51,8 +51,10 @@ typedef enum _snd_config_type {
         SND_CONFIG_TYPE_REAL,
 	/** Character string */
         SND_CONFIG_TYPE_STRING,
+        /** Pointer - runtime only - cannot be saved */
+        SND_CONFIG_TYPE_POINTER,
 	/** Compound */
-	SND_CONFIG_TYPE_COMPOUND,
+	SND_CONFIG_TYPE_COMPOUND = 1024,
 } snd_config_type_t;
 
 /** Config node handle */
@@ -60,10 +62,13 @@ typedef struct _snd_config snd_config_t;
 /** Config compound iterator */
 typedef struct _snd_config_iterator *snd_config_iterator_t;
 
+extern snd_config_t *snd_config;
+
 int snd_config_top(snd_config_t **config);
 
 int snd_config_load(snd_config_t *config, snd_input_t *in);
 int snd_config_save(snd_config_t *config, snd_output_t *out);
+int snd_config_update(void);
 
 int snd_config_search(snd_config_t *config, const char *key,
 		      snd_config_t **result);
@@ -74,10 +79,10 @@ int snd_config_search_definition(snd_config_t *config,
 				 snd_config_t **result);
 
 int snd_config_expand(snd_config_t *config, snd_config_t *root,
-		      const char *args, void *private_data,
+		      const char *args, snd_config_t *private_data,
 		      snd_config_t **result);
 int snd_config_evaluate(snd_config_t *config, snd_config_t *root,
-			void *private_data, snd_config_t **result);
+			snd_config_t *private_data, snd_config_t **result);
 
 int snd_config_add(snd_config_t *config, snd_config_t *leaf);
 int snd_config_delete(snd_config_t *config);
@@ -88,17 +93,24 @@ int snd_config_make(snd_config_t **config, const char *key,
 int snd_config_make_integer(snd_config_t **config, const char *key);
 int snd_config_make_real(snd_config_t **config, const char *key);
 int snd_config_make_string(snd_config_t **config, const char *key);
+int snd_config_make_pointer(snd_config_t **config, const char *key);
 int snd_config_make_compound(snd_config_t **config, const char *key, int join);
 
+snd_config_type_t snd_config_get_type(snd_config_t *config);
+
 int snd_config_set_id(snd_config_t *config, const char *id);
 int snd_config_set_integer(snd_config_t *config, long value);
 int snd_config_set_real(snd_config_t *config, double value);
 int snd_config_set_string(snd_config_t *config, const char *value);
 int snd_config_set_ascii(snd_config_t *config, const char *ascii);
+int snd_config_set_pointer(snd_config_t *config, const void *ptr);
+int snd_config_get_id(snd_config_t *config, const char **value);
 int snd_config_get_integer(snd_config_t *config, long *value);
 int snd_config_get_real(snd_config_t *config, double *value);
 int snd_config_get_string(snd_config_t *config, const char **value);
 int snd_config_get_ascii(snd_config_t *config, char **value);
+int snd_config_get_pointer(snd_config_t *config, const void **value);
+int snd_config_test_id(snd_config_t *config, const char *id);
 
 snd_config_iterator_t snd_config_iterator_first(snd_config_t *node);
 snd_config_iterator_t snd_config_iterator_next(snd_config_iterator_t iterator);
@@ -115,12 +127,6 @@ snd_config_t *snd_config_iterator_entry(snd_config_iterator_t iterator);
 #define snd_config_for_each(pos, next, node) \
 	for (pos = snd_config_iterator_first(node), next = snd_config_iterator_next(pos); pos != snd_config_iterator_end(node); pos = next, next = snd_config_iterator_next(pos))
 
-snd_config_type_t snd_config_get_type(snd_config_t *config);
-const char *snd_config_get_id(snd_config_t *config);
-
-extern snd_config_t *snd_config;
-int snd_config_update(void);
-
 /* Misc functions */
 
 int snd_config_get_bool_ascii(const char *ascii);
diff --git a/include/control.h b/include/control.h
index b13ed254..0c6ccc21 100644
--- a/include/control.h
+++ b/include/control.h
@@ -192,12 +192,6 @@ int snd_card_get_index(const char *name);
 int snd_card_get_name(int card, char **name);
 int snd_card_get_longname(int card, char **name);
 
-int snd_sctl_build(snd_sctl_t **ctl, snd_ctl_t *handle, snd_config_t *config,
-		   void *private_data, int mode);
-int snd_sctl_free(snd_sctl_t *handle);
-int snd_sctl_install(snd_sctl_t *handle);
-int snd_sctl_remove(snd_sctl_t *handle);
-
 int snd_ctl_open(snd_ctl_t **ctl, const char *name, int mode);
 int snd_ctl_close(snd_ctl_t *ctl);
 int snd_ctl_nonblock(snd_ctl_t *ctl, int nonblock);
@@ -482,9 +476,23 @@ void snd_hctl_elem_set_callback_private(snd_hctl_elem_t *obj, void * val);
 
 /** \} */
 
+/**
+ *  \defgroup SControl Setup Control Interface
+ *  \ingroup Control
+ *  The setup control interface - set or modify control elements from a configuration file.
+ *  \{
+ */
+
+int snd_sctl_build(snd_sctl_t **ctl, snd_ctl_t *handle, snd_config_t *config,
+		   snd_config_t *private_data, int mode);
+int snd_sctl_free(snd_sctl_t *handle);
+int snd_sctl_install(snd_sctl_t *handle);
+int snd_sctl_remove(snd_sctl_t *handle);
+
+/** \} */
+
 #ifdef __cplusplus
 }
 #endif
 
 #endif /* __ALSA_CONTROL_H */
-
diff --git a/include/global.h b/include/global.h
index cd72e552..f4cb2700 100644
--- a/include/global.h
+++ b/include/global.h
@@ -29,13 +29,14 @@
 #define __ALSA_GLOBAL_H_
 
 /**
- *  \defgroup Global Global defines
- *  Global defines
+ *  \defgroup Global Global defines and functions
+ *  Global defines and functions.
  *  \{
  */
 
 #ifndef ATTRIBUTE_UNUSED
-#define ATTRIBUTE_UNUSED __attribute__ ((__unused__)) /**< don't print warning when attribute is not used */
+/** do not print warning (gcc) when function parameter is not used */
+#define ATTRIBUTE_UNUSED __attribute__ ((__unused__))
 #endif
 
 #ifdef PIC /* dynamic build */
@@ -88,9 +89,9 @@ int snd_async_add_handler(snd_async_handler_t **handler, int fd,
 			  snd_async_callback_t callback, void *private_data);
 int snd_async_del_handler(snd_async_handler_t *handler);
 int snd_async_handler_get_fd(snd_async_handler_t *handler);
+int snd_async_handler_get_signo(snd_async_handler_t *handler);
 void *snd_async_handler_get_callback_private(snd_async_handler_t *handler);
 
 /** \} */
 
 #endif /* __ALSA_GLOBAL_H */
-
diff --git a/include/local.h b/include/local.h
index ecff86ea..74f0ddc0 100644
--- a/include/local.h
+++ b/include/local.h
@@ -113,8 +113,6 @@ typedef struct sndrv_seq_event snd_seq_event_t;
 #define SND_BIG_ENDIAN
 #endif
 
-extern int snd_async_signo;
-
 struct _snd_async_handler {
 	enum {
 		SND_ASYNC_HANDLER_GENERIC,
diff --git a/include/pcm.h b/include/pcm.h
index 526a0ca8..6ab6cef3 100644
--- a/include/pcm.h
+++ b/include/pcm.h
@@ -6,7 +6,8 @@
  * \author Takashi Iwai <tiwai@suse.de>
  * \date 1998-2001
  *
- * Application interface library for the ALSA driver
+ * Application interface library for the ALSA driver.
+ * See the \ref pcm page for more details.
  *
  *
  *   This library is free software; you can redistribute it and/or modify
@@ -34,7 +35,7 @@ extern "C" {
 
 /**
  *  \defgroup PCM PCM Interface
- *  The PCM Interface.
+ *  See the \ref pcm page for more details.
  *  \{
  */
 
@@ -59,6 +60,7 @@ typedef struct _snd_pcm_subformat_mask snd_pcm_subformat_mask_t;
 /** PCM class */
 typedef enum _snd_pcm_class {
 	/** standard device */
+
 	SND_PCM_CLASS_GENERIC = 0,
 	/** multichannel device */
 	SND_PCM_CLASS_MULTI,
@@ -388,8 +390,8 @@ int snd_pcm_unlink(snd_pcm_t *pcm);
 
 /**
  * \defgroup PCM_Info Stream Information
- * PCM Stream Information
  * \ingroup PCM
+ * See the \ref pcm page for more details.
  * \{
  */
 
@@ -422,8 +424,8 @@ void snd_pcm_info_set_stream(snd_pcm_info_t *obj, snd_pcm_stream_t val);
 
 /**
  * \defgroup PCM_HW_Params Hardware Parameters
- * PCM Hardware Parameters
  * \ingroup PCM
+ * See the \ref pcm page for more details.
  * \{
  */
 
@@ -596,8 +598,8 @@ unsigned int snd_pcm_hw_params_set_tick_time_last(snd_pcm_t *pcm, snd_pcm_hw_par
 
 /**
  * \defgroup PCM_SW_Params Software Parameters
- * PCM Software Parameters
  * \ingroup PCM
+ * See the \ref pcm page for more details.
  * \{
  */
 
@@ -637,8 +639,8 @@ snd_pcm_uframes_t snd_pcm_sw_params_get_silence_size(const snd_pcm_sw_params_t *
 
 /**
  * \defgroup PCM_Access Access Mask Functions
- * PCM Access Mask Functions
  * \ingroup PCM
+ * See the \ref pcm page for more details.
  * \{
  */
 
@@ -661,8 +663,8 @@ void snd_pcm_access_mask_reset(snd_pcm_access_mask_t *mask, snd_pcm_access_t val
 
 /**
  * \defgroup PCM_Format Format Mask Functions
- * PCM Format Mask Functions
  * \ingroup PCM
+ * See the \ref pcm page for more details.
  * \{
  */
 
@@ -685,8 +687,8 @@ void snd_pcm_format_mask_reset(snd_pcm_format_mask_t *mask, snd_pcm_format_t val
 
 /**
  * \defgroup PCM_SubFormat Subformat Mask Functions
- * PCM Subformat Mask Functions
  * \ingroup PCM
+ * See the \ref pcm page for more details.
  * \{
  */
 
@@ -709,8 +711,8 @@ void snd_pcm_subformat_mask_reset(snd_pcm_subformat_mask_t *mask, snd_pcm_subfor
 
 /**
  * \defgroup PCM_Status Status Functions
- * PCM Status Functions
  * \ingroup PCM
+ * See the \ref pcm page for more details.
  * \{
  */
 
@@ -735,8 +737,8 @@ snd_pcm_uframes_t snd_pcm_status_get_overrange(const snd_pcm_status_t *obj);
 
 /**
  * \defgroup PCM_Description Description Functions
- * PCM Description Functions
  * \ingroup PCM
+ * See the \ref pcm page for more details.
  * \{
  */
 
@@ -754,8 +756,8 @@ const char *snd_pcm_state_name(const snd_pcm_state_t state);
 
 /**
  * \defgroup PCM_Dump Debug Functions
- * PCM Debug Functions
  * \ingroup PCM
+ * See the \ref pcm page for more details.
  * \{
  */
 
@@ -771,8 +773,8 @@ int snd_pcm_status_dump(snd_pcm_status_t *status, snd_output_t *out);
 
 /**
  * \defgroup PCM_Direct Direct Access (MMAP) Functions
- * PCM Direct Access (MMAP) Functions
  * \ingroup PCM
+ * See the \ref pcm page for more details.
  * \{
  */
 
@@ -791,8 +793,8 @@ snd_pcm_sframes_t snd_pcm_mmap_readn(snd_pcm_t *pcm, void **bufs, snd_pcm_uframe
 
 /**
  * \defgroup PCM_Helpers Helper Functions
- * PCM Helper Functions
  * \ingroup PCM
+ * See the \ref pcm page for more details.
  * \{
  */
 
@@ -832,8 +834,8 @@ int snd_pcm_areas_copy(const snd_pcm_channel_area_t *dst_channels, snd_pcm_ufram
 
 /**
  * \defgroup PCM_Hook Hook Extension
- * PCM Hook Extension
  * \ingroup PCM
+ * See the \ref pcm page for more details.
  * \{
  */
 
@@ -861,8 +863,8 @@ int snd_pcm_hook_remove(snd_pcm_hook_t *hook);
 
 /**
  * \defgroup PCM_Scope Scope Plugin Extension
- * PCM Scope Plugin Extension
  * \ingroup PCM
+ * See the \ref pcm page for more details.
  * \{
  */
 
@@ -920,8 +922,8 @@ int16_t *snd_pcm_scope_s16_get_channel_buffer(snd_pcm_scope_t *scope,
 
 /**
  * \defgroup PCM_Deprecated Deprecated Functions
- * PCM Deprecated Functions
  * \ingroup PCM
+ * See the \ref pcm page for more details.
  * \{
  */
 
@@ -940,4 +942,3 @@ snd_pcm_xrun_t snd_pcm_sw_params_get_xrun_mode(const snd_pcm_sw_params_t *params
 #endif
 
 #endif /* __ALSA_PCM_H */
-