Update documentation of activate_grab_client().
[paraslash.git] / grab_client.c
index 50594f2..13b066b 100644 (file)
@@ -1,28 +1,19 @@
 /*
- * Copyright (C) 2006 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2006-2008 Andre Noll <maan@systemlinux.org>
  *
- *     This program is free software; you can redistribute it and/or modify
- *     it under the terms of the GNU General Public License as published by
- *     the Free Software Foundation; either version 2 of the License, or
- *     (at your option) any later version.
- *
- *     This program is distributed in the hope that it will be useful,
- *     but WITHOUT ANY WARRANTY; without even the implied warranty of
- *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- *     GNU General Public License for more details.
- *
- *     You should have received a copy of the GNU General Public License
- *     along with this program; if not, write to the Free Software
- *     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
+ * Licensed under the GPL v2. For licencing details see COPYING.
  */
 
 /**
- * \file grab_client.c functions for grabbing the stream at any position
- * in a filter chain
+ * \file grab_client.c Functions for grabbing the stream at any position
+ * in a filter chain.
  *
- * \sa filter_chain filter_chain_info filter
+ * \sa filter_chain filter_chain_info filter.
  */
 
+#include <sys/types.h>
+#include <dirent.h>
+
 #include "para.h"
 #include "grab_client.cmdline.h"
 #include "list.h"
@@ -35,7 +26,7 @@
 #include "fd.h"
 #include "crypt.h"
 
-/** grab clients that are not yet attached to a filter node */
+/** Grab clients that are not yet attached to a filter node. */
 struct list_head inactive_grab_client_list;
 
 static int max_num_filters(void)
@@ -154,12 +145,12 @@ static void gc_close(struct filter_callback *fcb)
 }
 
 /**
- * move a grab client from the inactive list to a filter node
+ * Move a grab client from the inactive list to a filter node.
  *
- * \param gc the grab client to activate
- * \param fn the filter node \a gc gets attached to
+ * \param gc The grab client to activate.
+ * \param fn The filter node \a gc gets attached to.
  *
- * \sa filter_node::callbacks, inactive_grab_client_list
+ * \sa filter_node::callbacks, inactive_grab_client_list.
  */
 void activate_grab_client(struct grab_client *gc, struct filter_node *fn)
 {
@@ -169,11 +160,11 @@ void activate_grab_client(struct grab_client *gc, struct filter_node *fn)
 }
 
 /**
- * activate inactive grab clients if possible
+ * Activate inactive grab clients if possible.
  *
- * \param slot_num audiod's slot for the new audio file
- * \param audio_format_num the number of the audio format of the new audio file
- * \param filter_list the list of activated filters for that new audio file
+ * \param slot_num Audiod's slot for the new audio file.
+ * \param audio_format_num The number of the audio format of the new audio file.
+ * \param fc The filter chain containing the activated filters.
  *
  * This is called from audiod.c when the current audio file changes. It loops
  * over all inactive grab clients and checks each grab client's configuration
@@ -182,10 +173,10 @@ void activate_grab_client(struct grab_client *gc, struct filter_node *fn)
  * appropriate filter_node.
  *
  * \sa filter_chain_info::filters, inactive_grab_client_list,
- * activate_grab_client
+ * activate_grab_client.
  */
 void activate_inactive_grab_clients(int slot_num, int audio_format_num,
-               struct list_head *filter_list)
+               struct filter_chain *fc)
 {
        struct grab_client *gc, *tmp;
        int i;
@@ -202,23 +193,21 @@ void activate_inactive_grab_clients(int slot_num, int audio_format_num,
                                num_filters(gc->audio_format_num)
                                < gc->conf->filter_num_arg)
                        continue;
-               i = 1;
-               list_for_each_entry(fn, filter_list, node) {
+               FOR_EACH_FILTER_NODE(fn, fc, i) {
                        if (gc->conf->filter_num_arg <= 0
-                               || i == gc->conf->filter_num_arg)
+                               || i == gc->conf->filter_num_arg + 1)
                                break;
-                       i++;
                }
                activate_grab_client(gc, fn);
        }
 }
 
 /**
- * check the command line options and allocate a grab_client structure
+ * Check the command line options and allocate a grab_client structure.
  *
- * \param fd the file descriptor of the client
- * \param line the command line
- * \param err non-zero if an error occured
+ * \param fd The file descriptor of the client.
+ * \param line The command line.
+ * \param err Non-zero if an error occurred.
  *
  * If the command line options given by \a argc and \a argv are valid.
  * allocate a struct grab_client and initialize it with this valid
@@ -228,7 +217,7 @@ void activate_inactive_grab_clients(int slot_num, int audio_format_num,
  * struct. On errors, it returns NULL and sets \a err appropriately.
  *
  * \sa grab_client, inactive_grab_client_list, activate_grab_client,
- * filter_node::callbacks
+ * filter_node::callbacks.
  */
 /*
  * argc, argv get freed when com_grab() returns, so we have to make a
@@ -272,14 +261,14 @@ err_out:
        return NULL;
 }
 
-/** initialize the grabbing subsystem.
+/**
+ * Initialize the grabbing subsystem.
  *
  * This has to be called once during startup before any other function from
  * grab_client.c may be used. It initializes \a inactive_grab_client_list.
  */
-void init_grabbing()
+void init_grabbing(void)
 {
-       PARA_INFO_LOG("%s", "grab init\n");
+       PARA_INFO_LOG("grab init\n");
        INIT_LIST_HEAD(&inactive_grab_client_list);
 }
-