send.h

   1 /*
   2  * Copyright (C) 2005-2010 Andre Noll <maan@systemlinux.org>
   3  *
   4  * Licensed under the GPL v2. For licencing details see COPYING.
   5  */
   6
   7 /** \file send.h Sender-related defines and structures. */
   8
   9 /** The sender subcommands. */
  10 enum {SENDER_ADD, SENDER_DELETE, SENDER_ALLOW, SENDER_DENY, SENDER_ON, SENDER_OFF, NUM_SENDER_CMDS};
  11
  12 /**
  13  * Each paraslash sender may register arbitrary many clients to the virtual
  14  * streaming system, possibly with varying fec parameters. In order to do so,
  15  * it must allocate a \a fec_client_parms structure and pass it to \ref
  16  * add_fec_client.
  17  *
  18  * Clients are automatically removed from that list by the vss if an error
  19  * occurs, or if the sender requests deletion of a client by calling \ref
  20  * vss_del_fec_client().
  21  */
  22 struct fec_client;
  23
  24 /** FEC parameters requested by FEC clients. */
  25 struct fec_client_parms {
  26         /** Number of data slices plus redundant slices. */
  27         uint8_t slices_per_group;
  28         /** Number of slices minus number of redundant slices. */
  29         uint8_t data_slices_per_group;
  30         /** Maximal number of bytes per slice, initially zero. */
  31         uint16_t max_slice_bytes;
  32 };
  33
  34 /**
  35  * Describes one supported sender of para_server.
  36  *
  37  * \sa http_send.c udp_send.c, dccp_send.c.
  38  */
  39 struct sender {
  40         /** The name of the sender. */
  41         const char *name;
  42         /**
  43          * The init function of this sender.
  44          *
  45          * It must fill in all function pointers of \a s as well as the \a
  46          * client_cmds array, see below. It should also do all necessary
  47          * preparations to init this sending facility, for example it could
  48          * open a tcp port.
  49          */
  50         void (*init)(struct sender *s);
  51         /**
  52          * Return the help text of this sender.
  53          *
  54          * The result must be dynamically allocated and is freed by the caller.
  55          */
  56         char* (*help)(void);
  57         /**
  58          * Return current status info about this sender.
  59          *
  60          * The result must be dynamically allocated and is freed by the caller.
  61          */
  62         char* (*info)(void);
  63         /**
  64          * The send-hook.
  65          *
  66          * It gets called whenever para_server is playing and the current
  67          * audio format handler indicates that another chunk of data should
  68          * be sent now. The two parameters \a current_chunk and \a chunks_sent
  69          * only differ if the stream was repositioned by the \a ff or \a jmp
  70          * command. Of course, \a buf is a pointer to the chunk of data which
  71          * should be sent, and \a len is the length of this buffer.
  72          */
  73         void (*send)(long unsigned current_chunk, long unsigned chunks_sent,
  74                 const char *buf, size_t len, const char *header_buf,
  75                 size_t header_len);
  76
  77         /**
  78          * Obtain the FEC parameters of a FEC client.
  79          *
  80          * This is called once by vss.c at the beginning of a stream. Senders
  81          * are supposed to set \a fcp to a struct which is suitable for the FEC
  82          * client identified by \a private_data.
  83          */
  84         int (*open)(void *client, struct fec_client_parms **fcp);
  85         /**
  86          * Send the next slice to a FEC client.
  87          *
  88          * Called by vss.c when the next slice should be sent to the FEC client
  89          * identified by \a private_data, the pointer which was previously
  90          * passed to vss_add_fec_target().
  91          */
  92         int (*send_fec)(char *buf, size_t num_bytes, void *private_data);
  93         /**
  94          * Add file descriptors to fd_sets.
  95          *
  96          * The pre_select function of each supported sender is called just before
  97          * para_server enters its main select loop. Each sender may add its own
  98          * file descriptors to the \a rfds or the \a wfds set.
  99          *
 100          * If a file descriptor was added, \a max_fileno must be increased by
 101          * this function, if necessary.
 102          *
 103          * \sa select(2).
 104          */
 105         void (*pre_select)(int *max_fileno, fd_set *rfds, fd_set *wfds);
 106         /**
 107          * Handle the file descriptors which are ready for I/O.
 108          *
 109          * If the pre_select hook added one ore more file descriptors to the
 110          * read or write set, this is the hook to check the result and do any
 111          * I/O on those descriptors which are ready for reading/writing.
 112          */
 113         void (*post_select)(fd_set *rfds, fd_set *wfds);
 114         /**
 115          * Terminate all connected clients.
 116          *
 117          * This is called e.g. if the stop command was executed. It should make
 118          * the clients aware of the end-of-file condition.
 119          */
 120         void (*shutdown_clients)(void);
 121         /**
 122          * Array of function pointers for the sender subcommands.
 123          *
 124          * Each sender may implement any subset of the sender commands by
 125          * filling in the appropriate function pointer in the array. A \p NULL
 126          * pointer means this command is not implemented by this sender.
 127          */
 128         int (*client_cmds[NUM_SENDER_CMDS])(struct sender_command_data*);
 129 };
 130
 131 /** Describes one client, connected to a paraslash sender. */
 132 struct sender_client {
 133         /** The file descriptor of the client. */
 134         int fd;
 135         /** The socket "name" of the client. */
 136         char *name;
 137         /** The position of this client in the client list. */
 138         struct list_head node;
 139         /** Non-zero if audio file header has been sent. */
 140         int header_sent;
 141         /** The list of pending chunks for this client. */
 142         struct chunk_queue *cq;
 143         /** Data specific to the particular sender. */
 144         void *private_data;
 145 };
 146
 147 /** Describes the current status of one paraslash sender. */
 148 struct sender_status {
 149         /** The file descriptor of the socket this sender is listening on. */
 150         int listen_fd;
 151         /** The TCP/DCCP port used by this sender. */
 152         int port;
 153         /** The current number of simultaneous connections. */
 154         int num_clients;
 155         /** The maximal number of simultaneous connections. */
 156         int max_clients;
 157         /** Whether the access control list is a whitelist. */
 158         int default_deny;
 159         /** The whitelist/blacklist. */
 160         struct list_head acl;
 161         /** The list of connected clients. */
 162         struct list_head client_list;
 163 };
 164
 165 void shutdown_client(struct sender_client *sc, struct sender_status *ss);
 166 void shutdown_clients(struct sender_status *ss);
 167 void send_chunk(struct sender_client *sc, struct sender_status *ss,
 168                 size_t max_bytes_per_write, long unsigned current_chunk,
 169                 const char *buf, size_t len, const char *header_buf,
 170                 size_t header_len);
 171 void init_sender_status(struct sender_status *ss, char **access_arg, int num_access_args,
 172         int port, int max_clients, int default_deny);
 173 char *get_sender_info(struct sender_status *ss, const char *name);
 174
 175 void generic_com_allow(struct sender_command_data *scd,
 176                 struct sender_status *ss);
 177 void generic_com_deny(struct sender_command_data *scd,
 178                 struct sender_status *ss);
 179 int generic_com_on(struct sender_status *ss, unsigned protocol);
 180 void generic_com_off(struct sender_status *ss);
 181 char *generic_sender_help(void);
 182 struct sender_client *accept_sender_client(struct sender_status *ss, fd_set *rfds);
 183 int send_queued_chunks(int fd, struct chunk_queue *cq,
 184                 size_t max_bytes_per_write);
 185 int parse_fec_url(const char *arg, struct sender_command_data *scd);