* [alsa-lib PATCH 2/4] Search-and-replace improve documentation language
[not found] <a0053dfb39d22118fce92031e4d6adac948b02fc.1325707699.git.aeikum@codeweavers.com>
@ 2012-01-04 20:11 ` Andrew Eikum
2012-01-05 6:43 ` Raymond Yau
2012-01-04 20:11 ` [alsa-lib PATCH 3/4] Improve hw_params documentation Andrew Eikum
2012-01-04 20:11 ` [alsa-lib PATCH 4/4] Improve snd_device_name_hint documentation Andrew Eikum
2 siblings, 1 reply; 5+ messages in thread
From: Andrew Eikum @ 2012-01-04 20:11 UTC (permalink / raw)
To: alsa-devel
[-- Attachment #1: Type: text/plain, Size: 137 bytes --]
---
src/pcm/pcm.c | 146 ++++++++++++++++++++++++++-------------------------------
1 files changed, 67 insertions(+), 79 deletions(-)
[-- Attachment #2: 0002-Search-and-replace-improve-documentation-language.patch --]
[-- Type: text/x-patch, Size: 19612 bytes --]
diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c
index bc5c6e4..dc91f79 100644
--- a/src/pcm/pcm.c
+++ b/src/pcm/pcm.c
@@ -2882,15 +2882,14 @@ int snd_pcm_hw_params_dump(snd_pcm_hw_params_t *params, snd_output_t *out)
}
/**
- * \brief Check, if hardware supports sample-resolution mmap for given configuration
+ * \brief Check if hardware supports sample-resolution mmap for given configuration
* \param params Configuration space
- * \return Boolean value
* \retval 0 Hardware doesn't support sample-resolution mmap
* \retval 1 Hardware supports sample-resolution mmap
*
- * The return value is always one when given configuration is not exactly one.
- * Usually, #snd_pcm_hw_params() function chooses one configuration
- * from the configuration space.
+ * This function should only be called when the configuration space
+ * contains a single configuration. Call #snd_pcm_hw_params to choose
+ * a single configuration from the configuration space.
*/
int snd_pcm_hw_params_can_mmap_sample_resolution(const snd_pcm_hw_params_t *params)
{
@@ -2903,15 +2902,14 @@ int snd_pcm_hw_params_can_mmap_sample_resolution(const snd_pcm_hw_params_t *para
}
/**
- * \brief Check, if hardware does double buffering for start/stop for given configuration
+ * \brief Check if hardware does double buffering for start/stop for given configuration
* \param params Configuration space
- * \return Boolean value
* \retval 0 Hardware doesn't do double buffering for start/stop
* \retval 1 Hardware does double buffering for start/stop
*
- * It is not allowed to call this function when given configuration is not exactly one.
- * Usually, #snd_pcm_hw_params() function chooses one configuration
- * from the configuration space.
+ * This function should only be called when the configuration space
+ * contains a single configuration. Call #snd_pcm_hw_params to choose
+ * a single configuration from the configuration space.
*/
int snd_pcm_hw_params_is_double(const snd_pcm_hw_params_t *params)
{
@@ -2924,15 +2922,14 @@ int snd_pcm_hw_params_is_double(const snd_pcm_hw_params_t *params)
}
/**
- * \brief Check, if hardware does double buffering for data transfers for given configuration
+ * \brief Check if hardware does double buffering for data transfers for given configuration
* \param params Configuration space
- * \return Boolean value
* \retval 0 Hardware doesn't do double buffering for data transfers
* \retval 1 Hardware does double buffering for data transfers
*
- * It is not allowed to call this function when given configuration is not exactly one.
- * Usually, #snd_pcm_hw_params() function chooses one configuration
- * from the configuration space.
+ * This function should only be called when the configuration space
+ * contains a single configuration. Call #snd_pcm_hw_params to choose
+ * a single configuration from the configuration space.
*/
int snd_pcm_hw_params_is_batch(const snd_pcm_hw_params_t *params)
{
@@ -2945,15 +2942,14 @@ int snd_pcm_hw_params_is_batch(const snd_pcm_hw_params_t *params)
}
/**
- * \brief Check, if hardware does block transfers for samples for given configuration
+ * \brief Check if hardware does block transfers for samples for given configuration
* \param params Configuration space
- * \return Boolean value
* \retval 0 Hardware doesn't block transfers
* \retval 1 Hardware does block transfers
*
- * It is not allowed to call this function when given configuration is not exactly one.
- * Usually, #snd_pcm_hw_params() function chooses one configuration
- * from the configuration space.
+ * This function should only be called when the configuration space
+ * contains a single configuration. Call #snd_pcm_hw_params to choose
+ * a single configuration from the configuration space.
*/
int snd_pcm_hw_params_is_block_transfer(const snd_pcm_hw_params_t *params)
{
@@ -2966,15 +2962,14 @@ int snd_pcm_hw_params_is_block_transfer(const snd_pcm_hw_params_t *params)
}
/**
- * \brief Check, if timestamps are monotonic for given configuration
+ * \brief Check if timestamps are monotonic for given configuration
* \param params Configuration space
- * \return Boolean value
* \retval 0 Device doesn't do monotomic timestamps
* \retval 1 Device does monotonic timestamps
*
- * It is not allowed to call this function when given configuration is not exactly one.
- * Usually, #snd_pcm_hw_params() function chooses one configuration
- * from the configuration space.
+ * This function should only be called when the configuration space
+ * contains a single configuration. Call #snd_pcm_hw_params to choose
+ * a single configuration from the configuration space.
*/
int snd_pcm_hw_params_is_monotonic(const snd_pcm_hw_params_t *params)
{
@@ -2987,15 +2982,14 @@ int snd_pcm_hw_params_is_monotonic(const snd_pcm_hw_params_t *params)
}
/**
- * \brief Check, if hardware supports overrange detection
+ * \brief Check if hardware supports overrange detection
* \param params Configuration space
- * \return Boolean value
* \retval 0 Hardware doesn't support overrange detection
* \retval 1 Hardware supports overrange detection
*
- * It is not allowed to call this function when given configuration is not exactly one.
- * Usually, #snd_pcm_hw_params() function chooses one configuration
- * from the configuration space.
+ * This function should only be called when the configuration space
+ * contains a single configuration. Call #snd_pcm_hw_params to choose
+ * a single configuration from the configuration space.
*/
int snd_pcm_hw_params_can_overrange(const snd_pcm_hw_params_t *params)
{
@@ -3008,15 +3002,14 @@ int snd_pcm_hw_params_can_overrange(const snd_pcm_hw_params_t *params)
}
/**
- * \brief Check, if hardware supports pause
+ * \brief Check if hardware supports pause
* \param params Configuration space
- * \return Boolean value
* \retval 0 Hardware doesn't support pause
* \retval 1 Hardware supports pause
*
- * It is not allowed to call this function when given configuration is not exactly one.
- * Usually, #snd_pcm_hw_params() function chooses one configuration
- * from the configuration space.
+ * This function should only be called when the configuration space
+ * contains a single configuration. Call #snd_pcm_hw_params to choose
+ * a single configuration from the configuration space.
*/
int snd_pcm_hw_params_can_pause(const snd_pcm_hw_params_t *params)
{
@@ -3029,15 +3022,14 @@ int snd_pcm_hw_params_can_pause(const snd_pcm_hw_params_t *params)
}
/**
- * \brief Check, if hardware supports resume
+ * \brief Check if hardware supports resume
* \param params Configuration space
- * \return Boolean value
* \retval 0 Hardware doesn't support resume
* \retval 1 Hardware supports resume
*
- * It is not allowed to call this function when given configuration is not exactly one.
- * Usually, #snd_pcm_hw_params() function chooses one configuration
- * from the configuration space.
+ * This function should only be called when the configuration space
+ * contains a single configuration. Call #snd_pcm_hw_params to choose
+ * a single configuration from the configuration space.
*/
int snd_pcm_hw_params_can_resume(const snd_pcm_hw_params_t *params)
{
@@ -3050,15 +3042,14 @@ int snd_pcm_hw_params_can_resume(const snd_pcm_hw_params_t *params)
}
/**
- * \brief Check, if hardware does half-duplex only
+ * \brief Check if hardware does half-duplex only
* \param params Configuration space
- * \return Boolean value
* \retval 0 Hardware doesn't do half-duplex
* \retval 1 Hardware does half-duplex
*
- * It is not allowed to call this function when given configuration is not exactly one.
- * Usually, #snd_pcm_hw_params() function chooses one configuration
- * from the configuration space.
+ * This function should only be called when the configuration space
+ * contains a single configuration. Call #snd_pcm_hw_params to choose
+ * a single configuration from the configuration space.
*/
int snd_pcm_hw_params_is_half_duplex(const snd_pcm_hw_params_t *params)
{
@@ -3071,15 +3062,14 @@ int snd_pcm_hw_params_is_half_duplex(const snd_pcm_hw_params_t *params)
}
/**
- * \brief Check, if hardware does joint-duplex (playback and capture are somewhat correlated)
+ * \brief Check if hardware does joint-duplex (playback and capture are somewhat correlated)
* \param params Configuration space
- * \return Boolean value
* \retval 0 Hardware doesn't do joint-duplex
* \retval 1 Hardware does joint-duplex
*
- * It is not allowed to call this function when given configuration is not exactly one.
- * Usually, #snd_pcm_hw_params() function chooses one configuration
- * from the configuration space.
+ * This function should only be called when the configuration space
+ * contains a single configuration. Call #snd_pcm_hw_params to choose
+ * a single configuration from the configuration space.
*/
int snd_pcm_hw_params_is_joint_duplex(const snd_pcm_hw_params_t *params)
{
@@ -3092,15 +3082,14 @@ int snd_pcm_hw_params_is_joint_duplex(const snd_pcm_hw_params_t *params)
}
/**
- * \brief Check, if hardware supports synchronized start with sample resolution
+ * \brief Check if hardware supports synchronized start with sample resolution
* \param params Configuration space
- * \return Boolean value
* \retval 0 Hardware doesn't support synchronized start
* \retval 1 Hardware supports synchronized start
*
- * It is not allowed to call this function when given configuration is not exactly one.
- * Usually, #snd_pcm_hw_params() function chooses one configuration
- * from the configuration space.
+ * This function should only be called when the configuration space
+ * contains a single configuration. Call #snd_pcm_hw_params to choose
+ * a single configuration from the configuration space.
*/
int snd_pcm_hw_params_can_sync_start(const snd_pcm_hw_params_t *params)
{
@@ -3115,7 +3104,6 @@ int snd_pcm_hw_params_can_sync_start(const snd_pcm_hw_params_t *params)
/**
* \brief Check if hardware can disable period wakeups
* \param params Configuration space
- * \return Boolean value
* \retval 0 Hardware cannot disable period wakeups
* \retval 1 Hardware can disable period wakeups
*/
@@ -3136,9 +3124,9 @@ int snd_pcm_hw_params_can_disable_period_wakeup(const snd_pcm_hw_params_t *param
* \param rate_den Pointer to returned rate denominator
* \return 0 otherwise a negative error code if the info is not available
*
- * It is not allowed to call this function when given configuration is not exactly one.
- * Usually, #snd_pcm_hw_params() function chooses one configuration
- * from the configuration space.
+ * This function should only be called when the configuration space
+ * contains a single configuration. Call #snd_pcm_hw_params to choose
+ * a single configuration from the configuration space.
*/
int snd_pcm_hw_params_get_rate_numden(const snd_pcm_hw_params_t *params,
unsigned int *rate_num, unsigned int *rate_den)
@@ -3158,9 +3146,9 @@ int snd_pcm_hw_params_get_rate_numden(const snd_pcm_hw_params_t *params,
* \param params Configuration space
* \return signification bits in sample otherwise a negative error code if the info is not available
*
- * It is not allowed to call this function when given configuration is not exactly one.
- * Usually, #snd_pcm_hw_params() function chooses one configuration
- * from the configuration space.
+ * This function should only be called when the configuration space
+ * contains a single configuration. Call #snd_pcm_hw_params to choose
+ * a single configuration from the configuration space.
*/
int snd_pcm_hw_params_get_sbits(const snd_pcm_hw_params_t *params)
{
@@ -3173,13 +3161,13 @@ int snd_pcm_hw_params_get_sbits(const snd_pcm_hw_params_t *params)
}
/**
- * \brief Get hard are FIFO size info from a configuration space
+ * \brief Get hardware FIFO size info from a configuration space
* \param params Configuration space
* \return FIFO size in frames otherwise a negative error code if the info is not available
*
- * It is not allowed to call this function when given configuration is not exactly one.
- * Usually, #snd_pcm_hw_params() function chooses one configuration
- * from the configuration space.
+ * This function should only be called when the configuration space
+ * contains a single configuration. Call #snd_pcm_hw_params to choose
+ * a single configuration from the configuration space.
*/
int snd_pcm_hw_params_get_fifo_size(const snd_pcm_hw_params_t *params)
{
@@ -3558,7 +3546,7 @@ void snd_pcm_hw_params_copy(snd_pcm_hw_params_t *dst, const snd_pcm_hw_params_t
* \brief Extract access type from a configuration space
* \param params Configuration space
* \param access Returned value
- * \return access type otherwise a negative error code if not exactly one is present
+ * \return access type otherwise a negative error code if the configuration space does not contain a single value
*/
#ifndef DOXYGEN
int INTERNAL(snd_pcm_hw_params_get_access)(const snd_pcm_hw_params_t *params, snd_pcm_access_t *access)
@@ -3659,7 +3647,7 @@ int snd_pcm_hw_params_get_access_mask(snd_pcm_hw_params_t *params, snd_pcm_acces
* \brief Extract format from a configuration space
* \param params Configuration space
* \param format returned format
- * \return format otherwise a negative error code if not exactly one is present
+ * \return format otherwise a negative error code if the configuration space does not contain a single value
*/
#ifndef DOXYGEN
int INTERNAL(snd_pcm_hw_params_get_format)(const snd_pcm_hw_params_t *params, snd_pcm_format_t *format)
@@ -3753,7 +3741,7 @@ void snd_pcm_hw_params_get_format_mask(snd_pcm_hw_params_t *params, snd_pcm_form
* \brief Extract subformat from a configuration space
* \param params Configuration space
* \param subformat Returned subformat value
- * \return subformat otherwise a negative error code if not exactly one is present
+ * \return subformat otherwise a negative error code if the configuration space does not contain a single value
*/
#ifndef DOXYGEN
int INTERNAL(snd_pcm_hw_params_get_subformat)(const snd_pcm_hw_params_t *params, snd_pcm_subformat_t *subformat)
@@ -3847,7 +3835,7 @@ void snd_pcm_hw_params_get_subformat_mask(snd_pcm_hw_params_t *params, snd_pcm_s
* \brief Extract channels from a configuration space
* \param params Configuration space
* \param val Returned channels count
- * \return 0 otherwise a negative error code if not exactly one is present
+ * \return 0 otherwise a negative error code if the configuration space does not contain a single value
*/
#ifndef DOXYGEN
int INTERNAL(snd_pcm_hw_params_get_channels)(const snd_pcm_hw_params_t *params, unsigned int *val)
@@ -4003,7 +3991,7 @@ int snd_pcm_hw_params_set_channels_last(snd_pcm_t *pcm, snd_pcm_hw_params_t *par
* \param params Configuration space
* \param val Returned approximate rate
* \param dir Sub unit direction
- * \return 0 otherwise a negative error code if not exactly one is present
+ * \return 0 otherwise a negative error code if the configuration space does not contain a single value
*
* Actual exact value is <,=,> the approximate one following dir (-1, 0, 1)
*/
@@ -4219,7 +4207,7 @@ int snd_pcm_hw_params_get_rate_resample(snd_pcm_t *pcm, snd_pcm_hw_params_t *par
}
/**
- * \brief Restrict a configuration space to allow the buffer accessible from outside
+ * \brief Restrict a configuration space to allow the buffer to be accessible from outside
* \param pcm PCM handle
* \param params Configuration space
* \param val 0 = disable, 1 = enable (default) exporting buffer
@@ -4306,7 +4294,7 @@ int snd_pcm_hw_params_get_period_wakeup(snd_pcm_t *pcm, snd_pcm_hw_params_t *par
* \param params Configuration space
* \param val Returned approximate period duration in us
* \param dir Sub unit direction
- * \return 0 otherwise a negative error code if not exactly one is present
+ * \return 0 otherwise a negative error code if the configuration space does not contain a single value
*
* Actual exact value is <,=,> the approximate one following dir (-1, 0, 1)
*/
@@ -4494,7 +4482,7 @@ int snd_pcm_hw_params_set_period_time_last(snd_pcm_t *pcm, snd_pcm_hw_params_t *
* \param params Configuration space
* \param val Returned approximate period size in frames
* \param dir Sub unit direction
- * \return 0 otherwise a negative error code if not exactly one is present
+ * \return 0 otherwise a negative error code if the configuration space does not contain a single value
*
* Actual exact value is <,=,> the approximate one following dir (-1, 0, 1)
*/
@@ -4731,7 +4719,7 @@ int snd_pcm_hw_params_set_period_size_integer(snd_pcm_t *pcm, snd_pcm_hw_params_
* \param params Configuration space
* \param val approximate periods per buffer
* \param dir Sub unit direction
- * \return 0 otherwise a negative error code if not exactly one is present
+ * \return 0 otherwise a negative error code if the configuration space does not contain a single value
*
* Actual exact value is <,=,> the approximate one following dir (-1, 0, 1)
*/
@@ -4931,7 +4919,7 @@ int snd_pcm_hw_params_set_periods_integer(snd_pcm_t *pcm, snd_pcm_hw_params_t *p
* \param params Configuration space
* \param val Returned buffer time in us
* \param dir Sub unit direction
- * \return 0 otherwise a negative error code if not exactly one is present
+ * \return 0 otherwise a negative error code if the configuration space does not contain a single value
*
* Actual exact value is <,=,> the approximate one following dir (-1, 0, 1)
*/
@@ -5119,7 +5107,7 @@ int snd_pcm_hw_params_set_buffer_time_last(snd_pcm_t *pcm, snd_pcm_hw_params_t *
* \brief Extract buffer size from a configuration space
* \param params Configuration space
* \param val Returned buffer size in frames
- * \return 0 otherwise a negative error code if not exactly one is present
+ * \return 0 otherwise a negative error code if the configuration space does not contain a single value
*/
#ifndef DOXYGEN
int INTERNAL(snd_pcm_hw_params_get_buffer_size)(const snd_pcm_hw_params_t *params, snd_pcm_uframes_t *val)
@@ -5318,7 +5306,7 @@ int snd_pcm_hw_params_set_buffer_size_last(snd_pcm_t *pcm, snd_pcm_hw_params_t *
* \param params Configuration space
* \param val Returned approximate tick duration in us
* \param dir Sub unit direction
- * \return 0 otherwise a negative error code if not exactly one is present
+ * \return 0 otherwise a negative error code if the configuration space does not contain a single value
*
* Actual exact value is <,=,> the approximate one following dir (-1, 0, 1)
*/
@@ -5508,7 +5496,7 @@ int snd_pcm_hw_params_set_tick_time_last(snd_pcm_t *pcm, snd_pcm_hw_params_t *pa
* \brief Get the minimum transfer align value in samples
* \param params Configuration space
* \param val Returned minimum align value
- * \return 0 otherwise a negative error code if not exactly one is present
+ * \return 0 otherwise a negative error code if the configuration space does not contain a single value
*/
int snd_pcm_hw_params_get_min_align(const snd_pcm_hw_params_t *params, snd_pcm_uframes_t *val)
{
[-- Attachment #3: Type: text/plain, Size: 0 bytes --]
^ permalink raw reply related [flat|nested] 5+ messages in thread* [alsa-lib PATCH 3/4] Improve hw_params documentation
[not found] <a0053dfb39d22118fce92031e4d6adac948b02fc.1325707699.git.aeikum@codeweavers.com>
2012-01-04 20:11 ` [alsa-lib PATCH 2/4] Search-and-replace improve documentation language Andrew Eikum
@ 2012-01-04 20:11 ` Andrew Eikum
2012-01-04 20:11 ` [alsa-lib PATCH 4/4] Improve snd_device_name_hint documentation Andrew Eikum
2 siblings, 0 replies; 5+ messages in thread
From: Andrew Eikum @ 2012-01-04 20:11 UTC (permalink / raw)
To: alsa-devel
[-- Attachment #1: Type: text/plain, Size: 129 bytes --]
---
include/pcm.h | 17 ++++++++++++++++-
src/pcm/pcm.c | 10 +++++++++-
2 files changed, 25 insertions(+), 2 deletions(-)
[-- Attachment #2: 0003-Improve-hw_params-documentation.patch --]
[-- Type: text/x-patch, Size: 2809 bytes --]
diff --git a/include/pcm.h b/include/pcm.h
index be355a9..4997557 100644
--- a/include/pcm.h
+++ b/include/pcm.h
@@ -44,8 +44,23 @@ extern "C" {
/** PCM generic info container */
typedef struct _snd_pcm_info snd_pcm_info_t;
-/** PCM hardware configuration space container */
+
+/** PCM hardware configuration space container
+ *
+ * snd_pcm_hw_params_t is an opaque structure which contains a set of possible
+ * PCM hardware configurations. For example, a given instance might include a
+ * range of buffer sizes, a range of period sizes, and a set of several sample
+ * formats. Some subset of all possible combinations these sets may be valid,
+ * but not necessarily any combination will be valid.
+ *
+ * When a parameter is set or restricted using a snd_pcm_hw_params_set*
+ * function, all of the other ranges will be updated to exclude as many
+ * impossible configurations as possible. Attempting to set a parameter
+ * outside of its acceptable range will result in the function failing
+ * and an error code being returned.
+ */
typedef struct _snd_pcm_hw_params snd_pcm_hw_params_t;
+
/** PCM software configuration container */
typedef struct _snd_pcm_sw_params snd_pcm_sw_params_t;
/** PCM status container */
diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c
index dc91f79..ea1afdc 100644
--- a/src/pcm/pcm.c
+++ b/src/pcm/pcm.c
@@ -809,7 +809,9 @@ int snd_pcm_hw_params_current(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
*
* The configuration is chosen fixing single parameters in this order:
* first access, first format, first subformat, min channels, min rate,
- * min period time, max buffer size, min tick time
+ * min period time, max buffer size, min tick time. If no mutually
+ * compatible set of parameters can be chosen, a negative error code
+ * will be returned.
*
* After this call, #snd_pcm_prepare() is called automatically and
* the stream is brought to \c #SND_PCM_STATE_PREPARED state.
@@ -817,6 +819,9 @@ int snd_pcm_hw_params_current(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
* The hardware parameters cannot be changed when the stream is
* running (active). The software parameters can be changed
* at any time.
+ *
+ * The configuration space will be updated to reflect the chosen
+ * parameters.
*/
int snd_pcm_hw_params(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
{
@@ -3183,6 +3188,9 @@ int snd_pcm_hw_params_get_fifo_size(const snd_pcm_hw_params_t *params)
* \brief Fill params with a full configuration space for a PCM
* \param pcm PCM handle
* \param params Configuration space
+ *
+ * The configuration space will be filled with all possible ranges
+ * for the PCM device.
*/
int snd_pcm_hw_params_any(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
{
[-- Attachment #3: Type: text/plain, Size: 0 bytes --]
^ permalink raw reply related [flat|nested] 5+ messages in thread* [alsa-lib PATCH 4/4] Improve snd_device_name_hint documentation
[not found] <a0053dfb39d22118fce92031e4d6adac948b02fc.1325707699.git.aeikum@codeweavers.com>
2012-01-04 20:11 ` [alsa-lib PATCH 2/4] Search-and-replace improve documentation language Andrew Eikum
2012-01-04 20:11 ` [alsa-lib PATCH 3/4] Improve hw_params documentation Andrew Eikum
@ 2012-01-04 20:11 ` Andrew Eikum
2 siblings, 0 replies; 5+ messages in thread
From: Andrew Eikum @ 2012-01-04 20:11 UTC (permalink / raw)
To: alsa-devel
[-- Attachment #1: Type: text/plain, Size: 115 bytes --]
---
src/control/namehint.c | 26 ++++++++++++++++----------
1 files changed, 16 insertions(+), 10 deletions(-)
[-- Attachment #2: 0004-Improve-snd_device_name_hint-documentation.patch --]
[-- Type: text/x-patch, Size: 2676 bytes --]
diff --git a/src/control/namehint.c b/src/control/namehint.c
index faaa5d5..19352be 100644
--- a/src/control/namehint.c
+++ b/src/control/namehint.c
@@ -517,15 +517,18 @@ static int add_software_devices(struct hint_list *list)
}
/**
- * \brief Return string list with device name hints.
+ * \brief Get a set of device name hints
* \param card Card number or -1 (means all cards)
* \param iface Interface identification (like "pcm", "rawmidi", "timer", "seq")
- * \param hints Result - array of string with device name hints
+ * \param hints Result - array of device name hints
* \result zero if success, otherwise a negative error code
*
- * Note: The device description is separated with '|' char.
+ * hints will receive a NULL-terminated array of device name hints,
+ * which can be passed to #snd_device_name_get_hint to extract usable
+ * values. When no longer needed, hints should be passed to
+ * #snd_device_name_free_hint to release resources.
*
- * User defined hints are gathered from namehint.IFACE tree like:
+ * User-defined hints are gathered from namehint.IFACE tree like:
*
* <code>
* namehint.pcm {<br>
@@ -534,6 +537,8 @@ static int add_software_devices(struct hint_list *list)
* }
* </code>
*
+ * Note: The device description is separated with '|' char.
+ *
* Special variables: defaults.namehint.showall specifies if all device
* definitions are accepted (boolean type).
*/
@@ -626,8 +631,8 @@ int snd_device_name_hint(int card, const char *iface, void ***hints)
}
/**
- * \brief Free a string list with device name hints.
- * \param hints A string list to free
+ * \brief Free a list of device name hints.
+ * \param hints List to free
* \result zero if success, otherwise a negative error code
*/
int snd_device_name_free_hint(void **hints)
@@ -646,16 +651,17 @@ int snd_device_name_free_hint(void **hints)
}
/**
- * \brief Get a hint Free a string list with device name hints.
+ * \brief Extract a value from a hint
* \param hint A pointer to hint
- * \param id Hint ID (see bellow)
+ * \param id Hint value to extract ("NAME", "DESC", or "IOID", see below)
* \result an allocated ASCII string if success, otherwise NULL
*
* List of valid IDs:
* NAME - name of device
* DESC - description of device
- * IOID - input / output identification (Input or Output strings),
- * not present (NULL) means both
+ * IOID - input / output identification ("Input" or "Output"), NULL means both
+ *
+ * The return value should be freed when no longer needed.
*/
char *snd_device_name_get_hint(const void *hint, const char *id)
{
[-- Attachment #3: Type: text/plain, Size: 0 bytes --]
^ permalink raw reply related [flat|nested] 5+ messages in thread