seq: update documentation for system call information

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>

diff --git a/src/seq/query.c b/src/seq/query.c
index 672687eac7d2b8a31b3ef674664fe72c32853270..f81ae04b8f69365322b10d641e95e09745b296ab 100644 (file)
--- a/src/seq/query.c
+++ b/src/seq/query.c
@@ -30,6 +30,8 @@ G_DEFINE_QUARK("alsaseq-error", alsaseq_error)
  * @error: A #GError.
  *
  * Allocate sysname string for ALSA sequencer and return it when exists.
+ *
+ * Nodes under sound subsystem in sysfs are used to gather the information.
  */
 void alsaseq_get_seq_sysname(gchar **sysname, GError **error)
 {
@@ -72,6 +74,8 @@ void alsaseq_get_seq_sysname(gchar **sysname, GError **error)
  * @error: A #GError.
  *
  * Allocate devnode string for ALSA Sequencer and return it when exists.
+ *
+ * Nodes under sound subsystem in sysfs are used to gather the information.
  */
 void alsaseq_get_seq_devnode(gchar **devnode, GError **error)
 {
@@ -114,6 +118,9 @@ void alsaseq_get_seq_devnode(gchar **devnode, GError **error)
  * @error: A #GError.
  *
  * Get information of ALSA Sequencer.
+ *
+ * The call of function executes open(2), close(2), and ioctl(2) system calls
+ * with SNDRV_SEQ_IOCTL_SYSTEM_INFO command for ALSA sequencer character device.
  */
 void alsaseq_get_system_info(ALSASeqSystemInfo **system_info, GError **error)
 {
@@ -159,6 +166,11 @@ void alsaseq_get_system_info(ALSASeqSystemInfo **system_info, GError **error)
  * @error: A #GError.
  *
  * Get the list of clients as the numerical ID.
+ *
+ * The call of function executes open(2), close(2), and ioctl(2) system calls
+ * with SNDRV_SEQ_IOCTL_CLIENT_ID, SNDRV_SEQ_IOCTL_SYSTEM_INFO, and
+ * SNDRV_SEQ_IOCTL_QUERY_NEXT_CLIENT command for ALSA sequencer character
+ * device.
  */
 void alsaseq_get_client_id_list(guint **entries, gsize *entry_count,
                                 GError **error)
@@ -242,6 +254,10 @@ void alsaseq_get_client_id_list(guint **entries, gsize *entry_count,
  * @error: A #GError.
  *
  * Get the information of client according to the numerical ID.
+ *
+ * The call of function executes open(2), close(2), and ioctl(2) system calls
+ * with SNDRV_SEQ_IOCTL_GET_CLIENT_INFO command for ALSA sequencer character
+ * device.
  */
 void alsaseq_get_client_info(guint client_id, ALSASeqClientInfo **client_info,
                              GError **error)
@@ -288,6 +304,10 @@ void alsaseq_get_client_info(guint client_id, ALSASeqClientInfo **client_info,
  * @error: A #GError.
  *
  * Get the list of numerical IDs for port added by the client.
+ *
+ * The call of function executes open(2), close(2), and ioctl(2) system calls
+ * with SNDRV_SEQ_IOCTL_GET_CLIENT_INFO and SNDRV_SEQ_IOCTL_QUERY_NEXT_PORT
+ * commands for ALSA sequencer character device.
  */
 void alsaseq_get_port_id_list(guint client_id, guint **entries,
                               gsize *entry_count, GError **error)
@@ -360,6 +380,10 @@ void alsaseq_get_port_id_list(guint client_id, guint **entries,
  * @error: A #GError.
  *
  * Get the information of port in client.
+ *
+ * The call of function executes open(2), close(2), and ioctl(2) system calls
+ * with SNDRV_SEQ_IOCTL_GET_PORT_INFO command for ALSA sequencer character
+ * device.
  */
 void alsaseq_get_port_info(guint client_id, guint port_id,
                            ALSASeqPortInfo **port_info, GError **error)
@@ -404,6 +428,10 @@ void alsaseq_get_port_info(guint client_id, guint port_id,
  * @error: A #GError.
  *
  * Get statistical information of memory pool for the given client.
+ *
+ * The call of function executes open(2), close(2), and ioctl(2) system calls
+ * with SNDRV_SEQ_IOCTL_GET_CLIENT_POOL command for ALSA sequencer character
+ * device.
  */
 void alsaseq_get_client_pool(gint client_id, ALSASeqClientPool **client_pool,
                              GError **error)
@@ -460,6 +488,9 @@ static void fill_data_with_result(struct snd_seq_port_subscribe *data,
  * @error: A #GError.
  *
  * Get the list of subscription for given address and query type.
+ *
+ * The call of function executes open(2), close(2), and ioctl(2) system calls
+ * with SNDRV_SEQ_IOCTL_QUERY_SUBS command for ALSA sequencer character device.
  */
 void alsaseq_get_subscription_list(const ALSASeqAddr *addr,
                                    ALSASeqQuerySubscribeType query_type,
@@ -531,6 +562,10 @@ void alsaseq_get_subscription_list(const ALSASeqAddr *addr,
  * @error: A #GError.
  *
  * Get the list of queue in ALSA Sequencer.
+ *
+ * The call of function executes open(2), close(2), and ioctl(2) system calls
+ * with SNDRV_SEQ_IOCTL_SYSTEM_INFO and SNDRV_SEQ_IOCTL_GET_QUEUE_INFO commands
+ * for ALSA sequencer character device.
  */
 void alsaseq_get_queue_id_list(guint **entries, gsize *entry_count,
                                GError **error)
@@ -606,6 +641,10 @@ void alsaseq_get_queue_id_list(guint **entries, gsize *entry_count,
  * @error: A #GError.
  *
  * Get the information of queue, according to the numerical ID.
+ *
+ * The call of function executes open(2), close(2), and ioctl(2) system calls
+ * with SNDRV_SEQ_IOCTL_GET_QUEUE_INFO command for ALSA sequencer character
+ * device.
  */
 void alsaseq_get_queue_info_by_id(guint queue_id, ALSASeqQueueInfo **queue_info,
                                   GError **error)
@@ -646,6 +685,10 @@ void alsaseq_get_queue_info_by_id(guint queue_id, ALSASeqQueueInfo **queue_info,
  * @error: A #GError.
  *
  * Get the information of queue, according to the name string.
+ *
+ * The call of function executes open(2), close(2), and ioctl(2) system calls
+ * with SNDRV_SEQ_IOCTL_GET_NAMED_QUEUE command for ALSA sequencer character
+ * device.
  */
 void alsaseq_get_queue_info_by_name(const gchar *name,
                                     ALSASeqQueueInfo **queue_info,
@@ -688,6 +731,10 @@ void alsaseq_get_queue_info_by_name(const gchar *name,
  * @error: A #GError.
  *
  * Get current status of queue.
+ *
+ * The call of function executes open(2), close(2), and ioctl(2) system calls
+ * with SNDRV_SEQ_IOCTL_GET_QUEUE_STATUS command for ALSA sequencer character
+ * device.
  */
 void alsaseq_get_queue_status(guint queue_id, ALSASeqQueueStatus **queue_status,
                               GError **error)

diff --git a/src/seq/user-client.c b/src/seq/user-client.c
index 636f75ad451283371afa28fb2b988dad4b8a6c61..dd3f877436079a1fd95660834a1a1c548e92efab 100644 (file)
--- a/src/seq/user-client.c
+++ b/src/seq/user-client.c
@@ -145,6 +145,10 @@ ALSASeqUserClient *alsaseq_user_client_new()
  * @error: A #GError.
  *
  * Open ALSA sequencer character device.
+ *
+ * The call of function executes open(2) system call, then executes ioctl(2)
+ * system call with SNDRV_SEQ_IOCTL_CLIENT_ID command for ALSA sequencer
+ * character device.
  */
 void alsaseq_user_client_open(ALSASeqUserClient *self, gint open_flag,
                               GError **error)
@@ -181,6 +185,9 @@ void alsaseq_user_client_open(ALSASeqUserClient *self, gint open_flag,
  * @error: A #GError.
  *
  * Get client information.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_SET_CLIENT_INFO command for ALSA sequencer character device.
  */
 void alsaseq_user_client_set_info(ALSASeqUserClient *self,
                                   ALSASeqClientInfo *client_info,
@@ -207,6 +214,9 @@ void alsaseq_user_client_set_info(ALSASeqUserClient *self,
  * @error: A #GError.
  *
  * Set client information.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_GET_CLIENT_INFO command for ALSA sequencer character device.
  */
 void alsaseq_user_client_get_info(ALSASeqUserClient *self,
                                   ALSASeqClientInfo *const *client_info,
@@ -234,6 +244,9 @@ void alsaseq_user_client_get_info(ALSASeqUserClient *self,
  * @error: A #GError.
  *
  * Create a port into the client.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_CREATE_PORT command for ALSA sequencer character device.
  */
 void alsaseq_user_client_create_port(ALSASeqUserClient *self,
                                      ALSASeqPortInfo *port_info,
@@ -264,6 +277,10 @@ void alsaseq_user_client_create_port(ALSASeqUserClient *self,
  * @port_id: The numerical ID of port.
  * @error: A #GError.
  *
+ * Update port information.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_SET_PORT_INFO command for ALSA sequencer character device.
  */
 void alsaseq_user_client_update_port(ALSASeqUserClient *self,
                                      ALSASeqPortInfo *port_info,
@@ -292,6 +309,9 @@ void alsaseq_user_client_update_port(ALSASeqUserClient *self,
  * @error: A #GError.
  *
  * Delete a port from the client.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_DELETE_PORT command for ALSA sequencer character device.
  */
 void alsaseq_user_client_delete_port(ALSASeqUserClient *self,
                                      guint8 port_id, GError **error)
@@ -315,6 +335,9 @@ void alsaseq_user_client_delete_port(ALSASeqUserClient *self,
  * @error: A #GError.
  *
  * Configure memory pool in the client.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_SET_CLIENT_POOL command for ALSA sequencer character device.
  */
 void alsaseq_user_client_set_pool(ALSASeqUserClient *self,
                                   ALSASeqClientPool *client_pool,
@@ -340,6 +363,9 @@ void alsaseq_user_client_set_pool(ALSASeqUserClient *self,
  * @error: A #GError.
  *
  * Get information of memory pool in the client.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_GET_CLIENT_POOL command for ALSA sequencer character device.
  */
 void alsaseq_user_client_get_pool(ALSASeqUserClient *self,
                                   ALSASeqClientPool *const *client_pool,
@@ -367,6 +393,9 @@ void alsaseq_user_client_get_pool(ALSASeqUserClient *self,
  * @error: A #GError.
  *
  * Deliver the event immediately, or schedule it into memory pool of the client.
+ *
+ * The call of function executes write(2) system call for ALSA sequencer
+ * character device.
  */
 void alsaseq_user_client_schedule_event(ALSASeqUserClient *self,
                                         ALSASeqEventCntr *ev_cntr,
@@ -462,6 +491,9 @@ static void seq_user_client_finalize_src(GSource *gsrc)
  * @error: A #GError.
  *
  * Allocate GSource structure to handle events from ALSA seq character device.
+ * In each iteration of GMainContext, the read(2) system call is exected to
+ * dispatch sequencer event for 'handle-event' signal, according to the result
+ * of poll(2) system call.
  */
 void alsaseq_user_client_create_source(ALSASeqUserClient *self,
                                        GSource **gsrc, GError **error)
@@ -513,6 +545,10 @@ void alsaseq_user_client_create_source(ALSASeqUserClient *self,
  * @error: A #GError.
  *
  * Operate subscription between two ports pointed by the data.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_SUBSCRIBE_PORT and SNDRV_SEQ_IOCTL_UNSUBSCRIBE_PORT commands
+ * for ALSA sequencer character device.
  */
 void alsaseq_user_client_operate_subscription(ALSASeqUserClient *self,
                                          ALSASeqSubscribeData *subs_data,
@@ -546,6 +582,9 @@ void alsaseq_user_client_operate_subscription(ALSASeqUserClient *self,
  *
  * Create a new queue owned by the client. The content of information is updated
  * if success.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_CREATE_QUEUE command for ALSA sequencer character device.
  */
 void alsaseq_user_client_create_queue(ALSASeqUserClient *self,
                                 ALSASeqQueueInfo *queue_info, GError **error)
@@ -570,6 +609,9 @@ void alsaseq_user_client_create_queue(ALSASeqUserClient *self,
  * @error: A #GError.
  *
  * Delete the queue owned by the client.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_DELETE_QUEUE command for ALSA sequencer character device.
  */
 void alsaseq_user_client_delete_queue(ALSASeqUserClient *self,
                                       guint queue_id, GError **error)
@@ -593,6 +635,9 @@ void alsaseq_user_client_delete_queue(ALSASeqUserClient *self,
  * @error: A #GError.
  *
  * Update owned queue according to the information.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_SET_QUEUE_INFO command for ALSA sequencer character device.
  */
 void alsaseq_user_client_update_queue(ALSASeqUserClient *self,
                                       ALSASeqQueueInfo *queue_info,
@@ -620,6 +665,9 @@ void alsaseq_user_client_update_queue(ALSASeqUserClient *self,
  * @error: A #GError.
  *
  * Get usage of the queue by the client.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_GET_QUEUE_CLIENT command for ALSA sequencer character device.
  */
 void alsaseq_user_client_get_queue_usage(ALSASeqUserClient *self,
                                          guint queue_id, gboolean *use,
@@ -649,6 +697,9 @@ void alsaseq_user_client_get_queue_usage(ALSASeqUserClient *self,
  * @error: A #GError.
  *
  * Start the queue to use or not.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_SET_QUEUE_CLIENT command for ALSA sequencer character device.
  */
 void alsaseq_user_client_set_queue_usage(ALSASeqUserClient *self,
                                          guint queue_id, gboolean use,
@@ -676,8 +727,10 @@ void alsaseq_user_client_set_queue_usage(ALSASeqUserClient *self,
  * @queue_tempo: The data of tempo for queue.
  * @error: A #GError.
  *
- *
  * Set the data of tempo to the queue.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_SET_QUEUE_TEMPO command for ALSA sequencer character device.
  */
 void alsaseq_user_client_set_queue_tempo(ALSASeqUserClient *self,
                                 guint queue_id, ALSASeqQueueTempo *queue_tempo,
@@ -705,6 +758,9 @@ void alsaseq_user_client_set_queue_tempo(ALSASeqUserClient *self,
  * @error: A #GError.
  *
  * Get the data of tempo for the queue.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_GET_QUEUE_TEMPO command for ALSA sequencer character device.
  */
 void alsaseq_user_client_get_queue_tempo(ALSASeqUserClient *self,
                                 guint queue_id, ALSASeqQueueTempo **queue_tempo,
@@ -736,6 +792,9 @@ void alsaseq_user_client_get_queue_tempo(ALSASeqUserClient *self,
  * @error: A #GError.
  *
  * Set the data of timer for the queue.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_SET_QUEUE_TIMER command for ALSA sequencer character device.
  */
 void alsaseq_user_client_set_queue_timer(ALSASeqUserClient *self,
                                          guint queue_id,
@@ -775,6 +834,9 @@ void alsaseq_user_client_set_queue_timer(ALSASeqUserClient *self,
  * @error: A #GError.
  *
  * Get the data of timer for the queue.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_GET_QUEUE_TIMER command for ALSA sequencer character device.
  */
 void alsaseq_user_client_get_queue_timer(ALSASeqUserClient *self,
                                          guint queue_id,
@@ -818,6 +880,9 @@ void alsaseq_user_client_get_queue_timer(ALSASeqUserClient *self,
  * @error: A #GError.
  *
  * Remove queued events according to the filter.
+ *
+ * The call of function executes ioctl(2) system call with
+ * SNDRV_SEQ_IOCTL_REMOVE_EVENTS command for ALSA sequencer character device.
  */
 void alsaseq_user_client_remove_events(ALSASeqUserClient *self,
                                        ALSASeqRemoveFilter *filter,