From: Richard Kettlewell Date: Sat, 22 Sep 2007 13:25:27 +0000 (+0100) Subject: doxygen X-Git-Tag: debian-1_5_99dev8~243^2~35 X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/commitdiff_plain/3f3bb97b482e831c349e069789d9a31f68098b9b doxygen --- diff --git a/lib/configuration.c b/lib/configuration.c index 5881f87..60b3e0e 100644 --- a/lib/configuration.c +++ b/lib/configuration.c @@ -49,32 +49,51 @@ #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(); diff --git a/lib/configuration.h b/lib/configuration.h index 5f0b8cc..c7b5b09 100644 --- a/lib/configuration.h +++ b/lib/configuration.h @@ -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 */