From: Andre Noll Date: Wed, 28 May 2025 00:24:09 +0000 (+0200) Subject: doxygen X-Git-Url: https://git.tuebingen.mpg.de/?a=commitdiff_plain;h=1fe908807afe77a45fb923d6f4b3bd82b2430029;p=paraslash.git doxygen --- diff --git a/audiod.c b/audiod.c index bdf8b713..1374abf8 100644 --- a/audiod.c +++ b/audiod.c @@ -1,6 +1,17 @@ /* Copyright (C) 2005 Andre Noll , see file COPYING. */ -/** \file audiod.c The paraslash's audio daemon. */ +/** \file audiod.c The paraslash's audio daemon. + * + * The para_audiod(1) executable is a single-threaded program which combines + * receivers, filters, writers, a client which runs the stat server command, + * and a dispatcher for command requests which arrive at the local socket. + * + * The functions in this file implement setup, teardown and streaming, + * employing the buffer tree API for the latter. The command dispatcher + * calls \ref dispatch_local_connection() of \ref audiod_command.c where the + * command handlers are defined. The functions of that file call the handful + * of public functions defined here or use the few non-static variables. + */ #include #include @@ -33,7 +44,7 @@ #include "write.h" #include "signal.h" -/** Array of error strings. */ +/** \cond doxygen_ignore */ DEFINE_PARA_ERRLIST; static struct lls_parse_result *lpr; @@ -47,28 +58,30 @@ __printf_2_3 void (*para_log)(int, const char*, ...) = daemon_log; /* Audio formats supported by audiod */ static const char *audio_formats[] = {AUDIOD_AUDIO_FORMAT_ARRAY}; #define NUM_AUDIO_FORMATS ARRAY_SIZE(audio_formats) +/* Iterate over all supported audio formats. */ +#define FOR_EACH_AUDIO_FORMAT(af) for (af = 0; af < NUM_AUDIO_FORMATS; af++) -/** Defines how audiod handles one supported audio format. */ +/* Defines how audiod handles one supported audio format. */ struct audio_format_info { - /** the receiver for this audio format */ + /* the receiver for this audio format */ int receiver_num; - /** Parsed receiver command line. */ + /* Parsed receiver command line. */ struct lls_parse_result *receiver_lpr; - /** the number of filters that should be activated for this audio format */ + /* the number of filters that should be activated for this audio format */ unsigned int num_filters; - /** Array of filter numbers to be activated. */ + /* Array of filter numbers to be activated. */ unsigned *filter_nums; - /** Pointer to the array of filter configurations. */ + /* Pointer to the array of filter configurations. */ void **filter_conf; - /** Parsed filter command line, one parse result per filter. */ + /* Parsed filter command line, one parse result per filter. */ struct lls_parse_result **filter_lpr; - /** the number of filters that should be activated for this audio format */ + /* the number of filters that should be activated for this audio format */ unsigned int num_writers; - /** Array of writer IDs to be activated. */ + /* Array of writer IDs to be activated. */ int *wids; - /** Parsed writer command line(s) */ + /* Parsed writer command line(s) */ struct lls_parse_result **writer_lpr; - /** do not start receiver/filters/writer before this time */ + /* do not start receiver/filters/writer before this time */ struct timeval restart_barrier; }; @@ -93,10 +106,10 @@ struct slot_info { #define RECEIVER_CMD(_a) lls_cmd((_a)->receiver_num, recv_cmd_suite) #define RECEIVER(_a) ((const struct receiver *)lls_user_data(RECEIVER_CMD(_a))) -/** Maximal number of simultaneous instances. */ +/* Maximal number of simultaneous instances. */ #define MAX_STREAM_SLOTS 5 -/** Iterate over all slots. */ +/* Iterate over all slots. */ #define FOR_EACH_SLOT(_slot) for (_slot = 0; _slot < MAX_STREAM_SLOTS; _slot++) /* @@ -105,13 +118,14 @@ struct slot_info { */ static struct slot_info slot[MAX_STREAM_SLOTS]; -/** The vss status flags audiod is interested in. */ +/* The vss status flags audiod is interested in. */ enum vss_status_flags { - /** Whether the 'N' flag is set. */ + /* Whether the 'N' flag is set. */ VSS_STATUS_FLAG_NEXT = 1, - /** The 'P' flag is set. */ + /* The 'P' flag is set. */ VSS_STATUS_FLAG_PLAYING = 2, }; +/* \endcond doxygen_ignore */ /** * The scheduler instance of para_audiod. @@ -123,32 +137,32 @@ struct sched sched = {.timeout = 0}; /* The task for obtaining para_server's status (para_client stat). */ struct status_task { - /** The associated task structure of audiod. */ + /* The associated task structure of audiod. */ struct task *task; - /** Client data associated with the stat task. */ + /* Client data associated with the stat task. */ struct client_task *ct; - /** Do not restart client command until this time. */ + /* Do not restart client command until this time. */ struct timeval restart_barrier; - /** Last time we received status data from para_server. */ + /* Last time we received status data from para_server. */ struct timeval last_status_read; size_t min_iqs; - /** The offset value announced by para_server. */ + /* The offset value announced by para_server. */ int offset_seconds; - /** The length of the current audio file as announced by para_server. */ + /* The length of the current audio file as announced by para_server. */ int length_seconds; - /** The start of the current stream from the view of para_server. */ + /* The start of the current stream from the view of para_server. */ struct timeval server_stream_start; - /** The average time deviation between para_server and para_audiod. */ + /* The average time deviation between para_server and para_audiod. */ struct timeval sa_time_diff; - /** Whether client time is ahead of server time. */ + /* Whether client time is ahead of server time. */ int sa_time_diff_sign; - /** The 'P' and the 'N' flags as announced by para_server. */ + /* The 'P' and the 'N' flags as announced by para_server. */ enum vss_status_flags vss_status; - /** Number of times the clock difference is to be checked. */ + /* Number of times the clock difference is to be checked. */ unsigned clock_diff_count; - /** When to start the next check for clock difference. */ + /* When to start the next check for clock difference. */ struct timeval clock_diff_barrier; - /** Number of the audio format as announced by para_server. */ + /* Number of the audio format as announced by para_server. */ int current_audio_format_num; /* The status task btrn is the child of the client task. */ struct btr_node *btrn; @@ -169,30 +183,21 @@ static struct signal_task *signal_task; static struct status_task status_task_struct; static uid_t *uid_whitelist; -/** - * The task that calls the status command of para_server. - * - * \sa \ref struct status_task. - */ +/* The task that calls the status command of para_server. */ static struct status_task *stat_task = &status_task_struct; struct command_task { - /** The local listening socket. */ + /* The local listening socket. */ int fd; - /** The associated task structure. */ + /* The associated task structure. */ struct task *task; }; -/** Iterate over all supported audio formats. */ -#define FOR_EACH_AUDIO_FORMAT(af) for (af = 0; af < NUM_AUDIO_FORMATS; af++) - -/** +/* * Get the audio format number. * - * \param name The name of the audio format. - * - * \return The audio format number on success, -E_UNSUPPORTED_AUDIO_FORMAT if - * \a name is not a supported audio format. + * Returns the audio format number on success, -E_UNSUPPORTED_AUDIO_FORMAT + * if the given name is not a supported audio format. */ static int get_audio_format_num(const char *name) { @@ -1439,10 +1444,17 @@ static void handle_help_flags(void) } /** - * the main function of para_audiod + * The main function of para_audiod(1). + * + * \param argc Command line options are parsed via the lopsub library. + * + * \param argv Options are defined in the audiod suite file. The various + * subcommands (on, off, stat, etc.) are realized in a separate suite file. * - * \param argc usual argument count - * \param argv usual argument vector + * At startup we create and register tasks to handle signals, to run the + * stat server subcommand and to dispatch requests from para_audioc(1) on + * the local socket. Additional tasks are created to download, filter and + * write the stream. * * \return EXIT_SUCCESS or EXIT_FAILURE *