chiark / gitweb /
doxygen
authorRichard Kettlewell <rjk@greenend.org.uk>
Sat, 22 Sep 2007 13:25:27 +0000 (14:25 +0100)
committerRichard Kettlewell <rjk@greenend.org.uk>
Sat, 22 Sep 2007 13:25:27 +0000 (14:25 +0100)
lib/configuration.c
lib/configuration.h

index 5881f87..60b3e0e 100644 (file)
 #include "regsub.h"
 #include "signame.h"
 
+/** @brief Path to config file 
+ *
+ * set_configfile() sets the deafult if it is null.
+ */
 char *configfile;
 
+/** @brief Config file parser state */
 struct config_state {
+  /** @brief Filename */
   const char *path;
+  /** @brief Line number */
   int line;
+  /** @brief Configuration object under construction */
   struct config *config;
 };
 
+/** @brief Current configuration */
 struct config *config;
 
+/** @brief One configuration item */
 struct conf {
+  /** @brief Name as it appears in the config file */
   const char *name;
+  /** @brief Offset in @ref config structure */
   size_t offset;
+  /** @brief Pointer to item type */
   const struct conftype *type;
+  /** @brief Pointer to item-specific validation routine */
   int (*validate)(const struct config_state *cs,
                  int nvec, char **vec);
 };
 
+/** @brief Type of a configuration item */
 struct conftype {
+  /** @brief Pointer to function to set item */
   int (*set)(const struct config_state *cs,
             const struct conf *whoami,
             int nvec, char **vec);
+  /** @brief Pointer to function to free item */
   void (*free)(struct config *c, const struct conf *whoami);
 };
 
+/** @brief Compute the address of an item */
 #define ADDRESS(C, TYPE) ((TYPE *)((char *)(C) + whoami->offset))
+/** @brief Return the value of an item */
 #define VALUE(C, TYPE) (*ADDRESS(C, TYPE))
 
 static int set_signal(const struct config_state *cs,
@@ -790,11 +809,12 @@ static int validate_address(const struct config_state attribute((unused)) *cs,
   }
 }
 
-/* configuration table */
-
+/** @brief Item name and and offset */
 #define C(x) #x, offsetof(struct config, x)
+/** @brief Item name and and offset */
 #define C2(x,y) #x, offsetof(struct config, y)
 
+/** @brief All configuration items */
 static const struct conf conf[] = {
   { C(alias),            &type_string,           validate_alias },
   { C(allow),            &type_stringlist_accum, validate_allow },
@@ -839,7 +859,7 @@ static const struct conf conf[] = {
   { C(username),         &type_string,           validate_any },
 };
 
-/* find a configuration item's definition by key */
+/** @brief Find a configuration item's definition by key */
 static const struct conf *find(const char *key) {
   int n;
 
@@ -848,7 +868,7 @@ static const struct conf *find(const char *key) {
   return &conf[n];
 }
 
-/* set a new configuration value */
+/** @brief Set a new configuration value */
 static int config_set(const struct config_state *cs,
                      int nvec, char **vec) {
   const struct conf *which;
@@ -869,7 +889,7 @@ static void config_error(const char *msg, void *u) {
   error(0, "%s:%d: %s", cs->path, cs->line, msg);
 }
 
-/* include a file by name */
+/** @brief Include a file by name */
 static int config_include(struct config *c, const char *path) {
   FILE *fp;
   char *buffer, *inputbuffer, **vec;
@@ -921,7 +941,7 @@ static int config_include(struct config *c, const char *path) {
   return ret;
 }
 
-/* make a new default config */
+/** @brief Make a new default configuration */
 static struct config *config_default(void) {
   struct config *c = xmalloc(sizeof *c);
   const char *logname;
@@ -959,12 +979,13 @@ static char *get_file(struct config *c, const char *name) {
   return s;
 }
 
+/** @brief Set the default configuration file */
 static void set_configfile(void) {
   if(!configfile)
     byte_xasprintf(&configfile, "%s/config", pkgconfdir);
 }
 
-/* free the config file */
+/** @brief Free a configuration object */
 static void config_free(struct config *c) {
   int n;
 
@@ -978,6 +999,7 @@ static void config_free(struct config *c) {
   }
 }
 
+/** @brief Set post-parse defaults */
 static void config_postdefaults(struct config *c) {
   struct config_state cs;
   const struct conf *whoami;
@@ -1033,7 +1055,7 @@ static void config_postdefaults(struct config *c) {
     fatal(0, "speaker_backend is network but broadcast is not set");
 }
 
-/* re-read the config file */
+/** @brief (Re-)read the config file */
 int config_read() {
   struct config *c;
   char *privconf;
@@ -1071,6 +1093,7 @@ int config_read() {
   return 0;
 }
 
+/** @brief Return the path to the private configuration file */
 char *config_private(void) {
   char *s;
 
@@ -1079,6 +1102,7 @@ char *config_private(void) {
   return s;
 }
 
+/** @brief Return the path to user's personal configuration file */
 char *config_userconf(const char *home, const struct passwd *pw) {
   char *s;
 
@@ -1086,7 +1110,8 @@ char *config_userconf(const char *home, const struct passwd *pw) {
   return s;
 }
 
-char *config_usersysconf(const struct passwd *pw ) {
+/** @brief Return the path to user-specific system configuration */
+char *config_usersysconf(const struct passwd *pw) {
   char *s;
 
   set_configfile();
index 5f0b8cc..c7b5b09 100644 (file)
@@ -29,24 +29,37 @@ struct real_pcre;
  * is always pointed to by @config@.  Values in @config@ are UTF-8 encoded.
  */
 
+/** @brief A list of strings */
 struct stringlist {
+  /** @brief Number of strings */
   int n;
+  /** @brief Array of strings */
   char **s;
 };
 
+/** @brief A list of list of strings */
 struct stringlistlist {
+  /** @brief Number of string lists */
   int n;
+  /** @brief Array of string lists */
   struct stringlist *s;
 };
 
+/** @brief A collection of tracks */
 struct collection {
+  /** @brief Module that supports this collection */
   char *module;
+  /** @brief Filename encoding */
   char *encoding;
+  /** @brief Root directory */
   char *root;
 };
 
+/** @brief A list of collections */
 struct collectionlist {
+  /** @brief Number of collections */
   int n;
+  /** @brief Array of collections */
   struct collection *s;
 };
 
@@ -76,54 +89,132 @@ struct transformlist {
   struct transform *t;
 };
 
+/** @brief System configuration */
 struct config {
   /* server config */
-  struct stringlistlist player;                /* players */
-  struct stringlistlist allow;         /* allowed users */
-  struct stringlist scratch;           /* scratch tracks */
-  long gap;                            /* gap between tracks */
-  long history;                                /* length of history */
-  struct stringlist trust;             /* trusted users */
-  const char *user;                    /* user to run as */
-  long nice_rescan;                    /* rescan subprocess niceness */
-  struct stringlist plugins;           /* plugin path */
-  struct stringlist stopword;          /* stopwords for track search */
-  struct collectionlist collection;    /* track collections */
+
+  /** @brief All players */
+  struct stringlistlist player;
+
+  /** @brief Allowed users */
+  struct stringlistlist allow;
+
+  /** @brief Scratch tracks */
+  struct stringlist scratch;
+
+  /** @brief Gap between tracks in seconds */
+  long gap;
+
+  /** @brief Maximum number of recent tracks to record in history */
+  long history;
+
+  /** @brief Trusted users */
+  struct stringlist trust;
+
+  /** @brief User for server to run as */
+  const char *user;
+
+  /** @brief Nice value for rescan subprocess */
+  long nice_rescan;
+
+  /** @brief Paths to search for plugins */
+  struct stringlist plugins;
+
+  /** @brief List of stopwords */
+  struct stringlist stopword;
+
+  /** @brief List of collections */
+  struct collectionlist collection;
+
+  /** @brief Database checkpoint byte limit */
   long checkpoint_kbyte;
+
+  /** @brief Databsase checkpoint minimum */
   long checkpoint_min;
-  char *mixer;                         /* mixer device file */
-  char *channel;                       /* mixer channel */
-  long prefsync;                       /* preflog sync intreval */
-  struct stringlist listen;            /* secondary listen address */
-  const char *alias;                   /* alias format */
-  int lock;                            /* server takes a lock */
-  long nice_server;                    /* nice value for server */
-  long nice_speaker;                   /* nice value for speaker */
-  const char *speaker_command;         /* command for speaker to run */
-  ao_sample_format sample_format;      /* sample format to enforce */
-  long sox_generation;                 /* sox syntax generation */
-  int speaker_backend;                 /* speaker backend */
-#define BACKEND_ALSA 0
-#define BACKEND_COMMAND 1
-#define BACKEND_NETWORK 2
-  /* shared client/server config */
-  const char *home;                    /* home directory for state files */
-  /* client config */
-  const char *username, *password;     /* our own username and password */
-  struct stringlist connect;           /* connect address */
-  /* web config */
-  struct stringlist templates;         /* template path */
-  const char *url;                     /* canonical URL */
-  long refresh;                                /* maximum refresh period */
+
+  /** @brief Path to mixer device */
+  char *mixer;
+
+  /** @brief Mixer channel to use */
+  char *channel;
+
+  long prefsync;                       /* preflog sync interval */
+
+  /** @brief Secondary listen address */
+  struct stringlist listen;
+
+  /** @brief Alias format string */
+  const char *alias;
+
+  /** @brief Enable server locking */
+  int lock;
+
+  /** @brief Nice value for server */
+  long nice_server;
+
+  /** @brief Nice value for speaker */
+  long nice_speaker;
+
+  /** @brief Command execute by speaker to play audio */
+  const char *speaker_command;
+
+  /** @brief Target sample format */
+  ao_sample_format sample_format;
+
+  /** @brief Sox syntax generation */
+  long sox_generation;
+
+  /** @brief Speaker backend
+   *
+   * Choices are @ref BACKEND_ALSA, @ref BACKEND_COMMAND or @ref
+   * BACKEND_NETWORK.
+   */
+  int speaker_backend;
+#define BACKEND_ALSA 0                 /**< Use ALSA (Linux only) */
+#define BACKEND_COMMAND 1              /**< Execute a command */
+#define BACKEND_NETWORK 2              /**< Transmit RTP  */
+
+  /** @brief Home directory for state files */
+  const char *home;
+
+  /** @brief Login username */
+  const char *username;
+
+  /** @brief Login password */
+  const char *password;
+
+  /** @brief Address to connect to */
+  struct stringlist connect;
+
+  /** @brief Directories to search for web templates */
+  struct stringlist templates;
+
+  /** @brief Canonical URL of web interface */
+  const char *url;
+
+  /** @brief Maximum refresh interval for web interface (seconds) */
+  long refresh;
+
+  /** @brief Facilities restricted to trusted users
+   *
+   * A bitmap of @ref RESTRICT_SCRATCH, @ref RESTRICT_REMOVE and @ref
+   * RESTRICT_MOVE.
+   */
   unsigned restrictions;               /* restrictions */
-  long queue_pad;                      /* how far to pad queue with
-                                        * random tracks */
-#define RESTRICT_SCRATCH 1
-#define RESTRICT_REMOVE 2
-#define RESTRICT_MOVE 4
+#define RESTRICT_SCRATCH 1             /**< Restrict scratching */
+#define RESTRICT_REMOVE 2              /**< Restrict removal */
+#define RESTRICT_MOVE 4                        /**< Restrict rearrangement */
+
+  /** @brief Target queue length */
+  long queue_pad;
+
   struct namepartlist namepart;                /* transformations */
-  int signal;                          /* termination signal */
-  const char *device;                  /* ALSA output device */
+
+  /** @brief Termination signal for subprocesses */
+  int signal;
+
+  /** @brief ALSA output device */
+  const char *device;
   struct transformlist transform;      /* path name transformations */
 
   struct stringlist broadcast;         /* audio broadcast address */