/** \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) \
/**
* 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.
*/
*/
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.
* 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*);
/** 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;
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. */
projects / paraslash.git / commitdiff