sender: add a hook to resolve target names
[paraslash.git] / 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  * Describes one supported sender of para_server.
14  *
15  * \sa http_send.c udp_send.c, dccp_send.c.
16  */
17 struct sender {
18         /** The name of the sender. */
19         const char *name;
20         /**
21          * The init function of this sender.
22          *
23          * It must fill in all function pointers of \a s as well as the \a
24          * client_cmds array, see below. It should also do all necessary
25          * preparations to init this sending facility, for example it could
26          * open a tcp port.
27          */
28         void (*init)(struct sender *s);
29         /**
30          * Return the help text of this sender.
31          *
32          * The result must be dynamically allocated and is freed by the caller.
33          */
34         char* (*help)(void);
35         /**
36          * Return current status info about this sender.
37          *
38          * The result must be dynamically allocated and is freed by the caller.
39          */
40         char* (*info)(void);
41         /**
42          * The send-hook.
43          *
44          * It gets called whenever para_server is playing and the current
45          * audio format handler indicates that another chunk of data should
46          * be sent now. The two parameters \a current_chunk and \a chunks_sent
47          * only differ if the stream was repositioned by the \a ff or \a jmp
48          * command. Of course, \a buf is a pointer to the chunk of data which
49          * should be sent, and \a len is the length of this buffer.
50          */
51         void (*send)(long unsigned current_chunk, long unsigned chunks_sent,
52                 const char *buf, size_t len, const char *header_buf,
53                 size_t header_len);
54         /**
55          * Add file descriptors to fd_sets.
56          *
57          * The pre_select function of each supported sender is called just before
58          * para_server enters its main select loop. Each sender may add its own
59          * file descriptors to the \a rfds or the \a wfds set.
60          *
61          * If a file descriptor was added, \a max_fileno must be increased by
62          * this function, if necessary.
63          *
64          * \sa select(2).
65          */
66         void (*pre_select)(int *max_fileno, fd_set *rfds, fd_set *wfds);
67         /**
68          * Handle the file descriptors which are ready for I/O.
69          *
70          * If the pre_select hook added one ore more file descriptors to the
71          * read or write set, this is the hook to check the result and do any
72          * I/O on those descriptors which are ready for reading/writing.
73          */
74         void (*post_select)(fd_set *rfds, fd_set *wfds);
75         /**
76          * Terminate all connected clients.
77          *
78          * This is called e.g. if the stop command was executed. It should make
79          * the clients aware of the end-of-file condition.
80          */
81         void (*shutdown_clients)(void);
82         /**
83          * Array of function pointers for the sender subcommands.
84          *
85          * Each sender may implement any subset of the sender commands by
86          * filling in the appropriate function pointer in the array. A \p NULL
87          * pointer means this command is not implemented by this sender.
88          */
89         int (*client_cmds[NUM_SENDER_CMDS])(struct sender_command_data*);
90         /**
91          * Resolve target-specific URL string
92          *
93          * This method must be defined if the sender supports the add/delete
94          * subcommands. It interprets a string specifying a target URL in a
95          * sender-specific fashion (e.g. embedded FEC string). It can also
96          * fill in sender-specific defaults if necessary.
97          */
98         int (*resolve_target)(const char *, struct sender_command_data *);
99 };
100
101 /** Describes one client, connected to a paraslash sender. */
102 struct sender_client {
103         /** The file descriptor of the client. */
104         int fd;
105         /** The socket "name" of the client. */
106         char *name;
107         /** The position of this client in the client list. */
108         struct list_head node;
109         /** Non-zero if audio file header has been sent. */
110         int header_sent;
111         /** The list of pending chunks for this client. */
112         struct chunk_queue *cq;
113         /** Data specific to the particular sender. */
114         void *private_data;
115 };
116
117 /**
118  * Each paraslash sender may register arbitrary many clients to the virtual
119  * streaming system, possibly with varying fec parameters. In order to do so,
120  * it must allocate a \a fec_client_parms structure and pass it to \ref
121  * vss_add_fec_client.
122  *
123  * Clients are automatically removed from that list by the vss if an error
124  * occurs, or if the sender requests deletion of a client by calling \ref
125  * vss_del_fec_client().
126  */
127
128 /** FEC parameters requested by FEC clients. */
129 struct fec_client_parms {
130         /** Number of data slices plus redundant slices. */
131         uint8_t slices_per_group;
132         /** Number of slices minus number of redundant slices. */
133         uint8_t data_slices_per_group;
134         /** Maximal number of bytes per slice, initially zero. */
135         uint16_t max_slice_bytes;
136         /**
137          * Transport-layer initialisation for FEC support.
138          *
139          * This optional function serves (a) to make the transport layer
140          * ready to send FEC slices and (b) to determine the Maximum
141          * Packet Size (MPS) supported by the connection. The MPS value
142          * determines the largest payload size. This value is used to
143          * send FEC slices that are not larger than the path MTU, to avoid
144          * fragmentation and to maximize packet utilization. The user can
145          * alternatively specify a slice size of up to this value.
146          */
147         int (*init_fec)(struct sender_client *sc);
148         /** Push out FEC-encoded packets */
149         int (*send_fec)(struct sender_client *sc, char *buf, size_t len);
150 };
151
152 /** Describes the current status of one paraslash sender. */
153 struct sender_status {
154         /** The file descriptor of the socket this sender is listening on. */
155         int listen_fd;
156         /** The TCP/DCCP port used by this sender. */
157         int port;
158         /** The current number of simultaneous connections. */
159         int num_clients;
160         /** The maximal number of simultaneous connections. */
161         int max_clients;
162         /** Whether the access control list is a whitelist. */
163         int default_deny;
164         /** The whitelist/blacklist. */
165         struct list_head acl;
166         /** The list of connected clients. */
167         struct list_head client_list;
168 };
169
170 void shutdown_client(struct sender_client *sc, struct sender_status *ss);
171 void shutdown_clients(struct sender_status *ss);
172 void init_sender_status(struct sender_status *ss, char **access_arg, int num_access_args,
173         int port, int max_clients, int default_deny);
174 char *get_sender_info(struct sender_status *ss, const char *name);
175
176 void generic_com_allow(struct sender_command_data *scd,
177                 struct sender_status *ss);
178 void generic_com_deny(struct sender_command_data *scd,
179                 struct sender_status *ss);
180 int generic_com_on(struct sender_status *ss, unsigned protocol);
181 void generic_com_off(struct sender_status *ss);
182 char *generic_sender_help(void);
183 struct sender_client *accept_sender_client(struct sender_status *ss, fd_set *rfds);
184 int send_queued_chunks(int fd, struct chunk_queue *cq);
185 int parse_fec_url(const char *arg, struct sender_command_data *scd);