From 036a98a74ce8dc9454e4b9fc12b3a6b4046e85b3 Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Mon, 9 Jun 2025 23:38:50 +0200 Subject: [PATCH] send.h --- send.h | 74 +++++++++++++++++++-------------------- send_common.c | 2 +- web/DoxygenLayout.xml | 6 +--- web/documentation.in.html | 1 + web/para.css | 4 +++ 5 files changed, 44 insertions(+), 43 deletions(-) diff --git a/send.h b/send.h index a9151358..775e1975 100644 --- a/send.h +++ b/send.h @@ -2,23 +2,34 @@ /** \file send.h Sender-related defines and structures. * - * The file contains a little preprocessor fu to create the sender_subcommand - * enumeration and the list of sender name strings without duplicating - * the commands. + * All senders are always compiled in and are linked into para_server(1). + * The core structure of the sender API is struct \ref sender. + * + * The dccp and udp senders employ the FEC (forward error correction) API + * defined in \ref fec.c to register FEC clients to the virtual streaming + * system, which maintains the FEC client list. Clients are removed from + * the list if a fatal error occurs, or if the sender requests deletion of a + * client by calling \ref vss_del_fec_client(). To register a FEC client, + * the senders allocate a \ref fec_client_parms structure and pass it to + * \ref vss_add_fec_client(). + * + * The file also contains a little preprocessor fu to create the + * sender_subcommand enumeration and the list of sender name strings without + * duplicating the commands. */ /** - * The list of sender subcommands. This is only defined once and expands - * to a bunch of \ref SENDER_SUBCOMMAND (without the plural s) calls. We - * shall define and then redefine \ref SENDER_SUBCOMMAND, expanding the \ref - * SENDER_SUBCOMMANDS macro after each definition. The output is suitable - * to either declare an enumeration or to define a string array. + * The list of sender subcommands. This is only defined once. We shall define + * and then redefine \ref SENDER_SUBCOMMAND (without the plural s), expanding + * \ref SENDER_SUBCOMMANDS after each definition. The two defintions result + * in output that is suitable to be part of an enumeration or a string array. * * The add and delete subcommands are only implemented by the udp sender * to add/delete one or more targets. The allow and deny subcommands * allow/deny connections from given IP address(es) and the on/off subcommands * activate/deactivate a sender. - */ + * + * \showinitializer */ #define SENDER_SUBCOMMANDS \ SENDER_SUBCOMMAND(add) \ SENDER_SUBCOMMAND(delete) \ @@ -56,8 +67,8 @@ enum sender_subcommand { /** * Describes one sender of para_server(1). * - * Each sender implements a bunch of methods. A method may be called by either - * a command handler + * Each sender implements a bunch of methods which are called in server or + * in command handler context, or both. * * \sa \ref http_send.c \ref udp_send.c, \ref dccp_send.c. */ @@ -71,33 +82,32 @@ struct sender { */ void (*init)(void); /** - * Return the help text of this sender. + * Return the dynamically allocated help text. * - * The result must be dynamically allocated and is freed by the caller. + * It will be freed by the caller. */ - char* (*help)(void); + char * (*help)(void); /** - * Return current status info about this sender. + * Return current status information. * - * The result must be dynamically allocated and is freed by the caller. + * Like the help command, the result must be dynamically allocated + * and is freed by the caller. */ - char* (*status)(void); + char * (*status)(void); /** * The send-hook. * - * It gets called whenever para_server is playing and the current - * audio format handler indicates that another chunk of data should - * be sent now. The two parameters \a current_chunk and \a chunks_sent - * only differ if the stream was repositioned by the \a ff or \a jmp - * command. Of course, \a buf is a pointer to the chunk of data which - * should be sent, and \a len is the length of this buffer. + * It gets called whenever para_server(1) is playing and the virtual + * streaming system detects that it is time to send another chunk + * of data. The two chunk values only differ if the stream was + * repositioned by the ff or jmp server subcommand. */ void (*send)(long unsigned current_chunk, long unsigned chunks_sent, const char *buf, size_t len, const char *header_buf, size_t header_len); /** Ask the scheduler to monitor file descriptors. */ void (*pre_monitor)(struct sched *s); - /** Perform I/O on the file descriptors which are ready. */ + /** Send data to clients whose file descriptor is ready for I/O. */ void (*post_monitor)(struct sched *s); /** * Terminate all connected clients. @@ -112,7 +122,7 @@ struct sender { * Array of function pointers for the sender subcommands. * * Each sender may implement any subset of the sender commands by - * filling in the appropriate function pointer in the array. A \p NULL + * filling in the appropriate function pointer in the array. A NULL * pointer means this command is not implemented by this sender. */ int (*client_cmds[NUM_SENDER_CMDS])(struct sender_command_data*); @@ -129,10 +139,11 @@ struct sender { /** NULL-terminated list, defined in \ref vss.c. */ extern const struct sender * const senders[]; + /** Iterate over all senders. */ #define FOR_EACH_SENDER(_i) for ((_i) = 0; senders[(_i)]; (_i)++) -/** Describes one client, connected to a paraslash sender. */ +/** Describes one connected client. */ struct sender_client { /** The file descriptor of the client. */ int fd; @@ -148,17 +159,6 @@ struct sender_client { void *private_data; }; -/** - * Each paraslash sender may register arbitrary many clients to the virtual - * streaming system, possibly with varying fec parameters. In order to do so, - * it must allocate a \a fec_client_parms structure and pass it to \ref - * vss_add_fec_client. - * - * Clients are automatically removed from that list by the vss if an error - * occurs, or if the sender requests deletion of a client by calling \ref - * vss_del_fec_client(). - */ - /** FEC parameters requested by FEC clients. */ struct fec_client_parms { /** Number of data slices plus redundant slices. */ diff --git a/send_common.c b/send_common.c index 324e4001..1e524de5 100644 --- a/send_common.c +++ b/send_common.c @@ -178,7 +178,7 @@ void free_sender_status(const struct sender_status *ss) * \param ss The sender. * \param name Used for printing the header line. * - * \return The string printed in the "si" command. + * \return The string printed by the "sender status" subcommand. */ __malloc char *generic_sender_status(struct sender_status *ss, const char *name) { diff --git a/web/DoxygenLayout.xml b/web/DoxygenLayout.xml index 24790154..37b49133 100644 --- a/web/DoxygenLayout.xml +++ b/web/DoxygenLayout.xml @@ -135,20 +135,16 @@ - + - - - - diff --git a/web/documentation.in.html b/web/documentation.in.html index 61239b8f..95fcbb85 100644 --- a/web/documentation.in.html +++ b/web/documentation.in.html @@ -45,6 +45,7 @@ subsystem. This selection is not exhaustive, though.

[Buffer Trees] [Audio Format Handlers] [Virtual Streaming System] + [Forward Error Correction] [Audio File Selector] [Senders] [Receivers] diff --git a/web/para.css b/web/para.css index 893aabfb..3e12d5cc 100644 --- a/web/para.css +++ b/web/para.css @@ -12,6 +12,10 @@ td { vertical-align: top; } +h2.groupheader { + color: #ffffff; +} + span.slogan { font-size: 200%; font-weight: bold; -- 2.39.5