[-,seq,1/1] seq: improve documentation about new get pid/card functions
diff mbox

Message ID 1483450422-8577-1-git-send-email-agoode@google.com
State New
Headers show

Commit Message

Adam Goode Jan. 3, 2017, 1:33 p.m. UTC
Document the technique for determining if the running kernel supports
the new snd_seq_client_info_get_pid and snd_seq_client_info_get_card
functions. Also add a little information about how to use these
functions and add some cross references.

Signed-off-by: Adam Goode <agoode@google.com>

Comments

Takashi Iwai Jan. 3, 2017, 4:49 p.m. UTC | #1
On Tue, 03 Jan 2017 14:33:42 +0100,
Adam Goode wrote:
> 
> Document the technique for determining if the running kernel supports
> the new snd_seq_client_info_get_pid and snd_seq_client_info_get_card
> functions. Also add a little information about how to use these
> functions and add some cross references.
> 
> Signed-off-by: Adam Goode <agoode@google.com>

Applied, thanks.


Takashi

Patch
diff mbox

diff --git a/src/seq/seq.c b/src/seq/seq.c
index 9279830..b206e2f 100644
--- a/src/seq/seq.c
+++ b/src/seq/seq.c
@@ -1530,7 +1530,25 @@  int snd_seq_client_info_get_error_bounce(const snd_seq_client_info_t *info)
  * \param info client_info container
  * \return card number or -1 if value is not available.
  *
- * Only available for SND_SEQ_KERNEL_CLIENT clients.
+ * Only available for #SND_SEQ_KERNEL_CLIENT clients.
+ *
+ * The card number can be used to query state about the hardware
+ * device providing this client, by concatenating <code>"hw:CARD="</code>
+ * with the card number and using it as the <code>name</code> parameter
+ * to #snd_ctl_open().
+ *
+ * \note
+ * The return value of -1 is returned for two different conditions: when the
+ * running kernel does not support this operation, and when the client
+ * does not have a hardware card attached. See
+ * #snd_seq_client_info_get_pid() for a way to determine if the
+ * currently running kernel has support for this operation.
+ *
+ * \sa snd_seq_client_info_get_pid(),
+ *     snd_card_get_name(),
+ *     snd_card_get_longname(),
+ *     snd_ctl_open(),
+ *     snd_ctl_card_info()
  */
 int snd_seq_client_info_get_card(const snd_seq_client_info_t *info)
 {
@@ -1543,7 +1561,29 @@  int snd_seq_client_info_get_card(const snd_seq_client_info_t *info)
  * \param info client_info container
  * \return pid or -1 if value is not available.
  *
- * Only available for SND_SEQ_USER_CLIENT clients.
+ * Only available for #SND_SEQ_USER_CLIENT clients.
+ *
+ * \note
+ * The functionality for getting a client's PID and getting a
+ * client's card was added to the kernel at the same time, so you can
+ * use this function to determine if the running kernel
+ * supports reporting these values. If your own client has a valid
+ * PID as reported by this function, then the running kernel supports
+ * both #snd_seq_client_info_get_card() and #snd_seq_client_info_get_pid().
+ *
+ * \note
+ * Example code for determining kernel support:
+ * \code
+ *   int is_get_card_or_pid_supported(snd_seq_t *seq)
+ *   {
+ *   	snd_seq_client_info_t *my_client_info;
+ *   	snd_seq_client_info_alloca(&my_client_info);
+ *   	snd_seq_get_client_info(seq, my_client_info);
+ *   	return snd_seq_client_info_get_pid(my_client_info) != -1;
+ *   }
+ * \endcode
+ *
+ * \sa snd_seq_client_info_get_card()
  */
 int snd_seq_client_info_get_pid(const snd_seq_client_info_t *info)
 {