filter.h

   1 /*
   2  * Copyright (C) 2005-2006 Andre Noll <maan@systemlinux.org>
   3  *
   4  *     This program is free software; you can redistribute it and/or modify
   5  *     it under the terms of the GNU General Public License as published by
   6  *     the Free Software Foundation; either version 2 of the License, or
   7  *     (at your option) any later version.
   8  *
   9  *     This program is distributed in the hope that it will be useful,
  10  *     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  *     GNU General Public License for more details.
  13  *
  14  *     You should have received a copy of the GNU General Public License
  15  *     along with this program; if not, write to the Free Software
  16  *     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
  17  */
  18
  19 /** \file filter.h filter-related structures and exported symbols from filter_chain.c */
  20
  21 /**
  22  * describes one running instance of a chain of filters
  23  *
  24  */
  25 struct filter_chain_info {
  26 /**
  27  *
  28  *
  29  * the number of channels of the current stream
  30  *
  31  * Set by the decoding filter
  32  */
  33         unsigned int channels;
  34 /**
  35  *
  36  *
  37  * current samplerate in Hz
  38  *
  39  * Set by the decoding filter
  40  */
  41         unsigned int samplerate;
  42 /**
  43  *
  44  *
  45  * the list containing all filter nodes in this filter chain
  46  */
  47         struct list_head filters;
  48 /**
  49  *
  50  *
  51  * the input buffer of the filter chain
  52  *
  53  * This is set to point to the output buffer of the receiving application (the
  54  * buffer used to read from stdin for para_filter; the output buffer of the
  55  * current receiver for para_audiod)
  56  */
  57         char *inbuf;
  58 /**
  59  *
  60  *
  61  * the output buffer of the filter chain
  62  *
  63  * Points to the output buffer of the last filter in the filter chain
  64 **/
  65         char *outbuf;
  66 /**
  67  *
  68  *
  69  * pointer to variable containing the number of bytes loaded in the input buffer
  70  */
  71         size_t *in_loaded;
  72 /**
  73  *
  74  *
  75  * pointer to variable containing the number of bytes loaded in the output buffer
  76  */
  77         size_t *out_loaded;
  78 /**
  79  *
  80  *
  81  * non-zero if end of file was encountered
  82  */
  83         int *eof;
  84 /**
  85  *
  86  *
  87  * non-zero if an error occured
  88  */
  89         int error;
  90 };
  91
  92 /**
  93  * describes one running instance of a filter
  94 */
  95 struct filter_node {
  96 /**
  97  *
  98  *
  99  * a pointer to the corresponding filter struct
 100  */
 101         struct filter *filter;
 102 /**
 103  *
 104  *
 105  * the filter chain this filter node belongs to
 106  */
 107         struct filter_chain_info *fci;
 108 /**
 109  *
 110  *
 111  * the position of the filter in the corresponding filter chain
 112  *
 113  * all filters that make up the filter chains are organized in a doubly
 114  * linked list.
 115  */
 116         struct list_head node;
 117 /**
 118  *
 119  *
 120  * each filter may store any filter-specific information about the particular
 121  * instance of the filter here.
 122  */
 123         void *private_data;
 124 /**
 125  *
 126  *
 127  * the output buffer
 128  */
 129         char *buf;
 130 /**
 131  * the size of the output buffer
 132  */
 133         size_t bufsize;
 134 /**
 135  *
 136  *
 137  * the number of bytes currently loaded in \a buf
 138  */
 139         size_t loaded;
 140 /**
 141  *
 142  *
 143  * the list of registered callbacks
 144  */
 145         struct list_head callbacks;
 146 /**
 147  *
 148  * a pointer to the configuration of this instance
 149  */
 150         void *conf;
 151 };
 152
 153 /**
 154  * used to manage grab clients
 155  *
 156  * An application using paraslash's filter subsystem may register any number of
 157  * callbacks for each filter_node. It is possible to attach a filter callback
 158  * while the filter is running. This is used for stream grabbing in
 159  * para_audiod: Whenever a client sends the 'grab' command, para_audiod adds a
 160  * filter callback to the list of callbacks for the filter node specified in
 161  * the grab command.
 162  */
 163 struct filter_callback {
 164 /**
 165  *
 166  *
 167  * all callbacks are organized in a doubly linked list
 168  */
 169         struct list_head node;
 170 /**
 171  *
 172  *
 173  * private data
 174  *
 175  * May be initialized by the application before registering the callback. This
 176  * pointer is not used by the filter subsystem. It is provided for use within
 177  * the input/ouput/close callback functions.
 178  */
 179         void *data;
 180 /**
 181  *
 182  *
 183  * the input callback
 184  *
 185  * In not \p NULL, the filter subsystem calls this function whenever the filter
 186  * consumed some or all of its input buffer. A pointer to the buffer of consumed
 187  * data, its length and a pointer to the own \a filter_callback structure are passed
 188  * to \a input_cb. The input callback is expected to return a negative value on errors.
 189  */
 190         int (*input_cb)(char *buf, size_t len, struct filter_callback *fc);
 191 /**
 192  *
 193  *
 194  * the output callback
 195  *
 196  * If not NULL, this is called whenever the filter produces output. A pointer
 197  * to the output data, its length and a pointer to the own \a filter_callback
 198  * structure are passed to \a output_cb. Like the input callback, the output
 199  * callback is expected to return a negative value on errors.
 200  */
 201         int (*output_cb)(char *buf, size_t len, struct filter_callback *fc);
 202 /**
 203  *
 204  *
 205  * the callback close function
 206  *
 207  * This gets called whenever the input/ouput callback returned an error, or if
 208  * the filter chain is going to be destroyed, e.g. because the end of the
 209  * stream was encounterd. It is assumed to succeed.
 210  */
 211         void (*close)(struct filter_callback *fc);
 212 };
 213
 214
 215 void close_filters(struct filter_chain_info *fci);
 216 int filter_io(struct filter_chain_info *fci);
 217 void filter_init(struct filter *all_filters);
 218 int check_filter_arg(char *filter_arg, void **conf);
 219 int del_filter_callback(struct filter_callback *fcb);
 220
 221 /**
 222  * the structure associated with a paraslash filter
 223  *
 224  * Paraslash filters are "modules" which are used to transform an audio stream.
 225  * struct filter contains pointers to functions that must be supplied by the
 226  * filter code in order to be used by the driving application (currently
 227  * para_audiod and para_filter).
 228  *
 229  * Note: As several instances of the same filter may be running at the same
 230  * time, all these filter functions must be reentrant; no static non-constant
 231  * variables may be used.
 232  * \sa mp3dec.c, oggdec.c, wav.c, compress.c, filter_node
 233  */
 234 struct filter {
 235 /**
 236  *
 237  *
 238  * the name of the filter
 239  */
 240 const char *name;
 241 /**
 242  *
 243  *
 244  * pointer to the filter init routine
 245  *
 246  * This function is only called once at startup. It must initialize the
 247  * other non-optional function pointers of \a f.
 248  */
 249 void (*init)(struct filter *f);
 250 /**
 251  *
 252  *
 253  * open one instance of this filter
 254  *
 255  * This should allocate the output buffer of the given filter node and do any
 256  * other filter-specific preparations like initializing the private_data member
 257  * of \a fn suitably. The open function is assumed to succeed.
 258  */
 259 void (*open)(struct filter_node *fn);
 260 /**
 261  *
 262  *
 263  * convert (filter) the given data
 264  *
 265  * Pointer to the converting function of the filter. It should convert the
 266  * given input buffer \a inbuf which is of length \a len to the previoulsy
 267  * reserved output buffer of \a fn. On success, it must return the number of
 268  * bytes it consumed from \a inbuf. On errors, a negative number indicating the
 269  * kind of the error must be returned.
 270  *
 271  * A zero return value just means that nothing was converted (probably because
 272  * the input buffer was too small). This is not interpreted as an error.
 273  */
 274 ssize_t (*convert)(char *inbuf, size_t len, struct filter_node *fn);
 275 /**
 276  *
 277  *
 278  * close one instance of this filter
 279  *
 280  * Free all resources of associated with \a fn that were previously allocated
 281  * by the open() function.
 282  */
 283 void (*close)(struct filter_node *fn);
 284 /**
 285  *
 286  *
 287  * print the help text for this filter and exit
 288  *
 289  * This is optional and it is not necessary to initialize this pointer if
 290  * the filter does not have a help text.
 291  */
 292 void (*print_help)(void);
 293 /**
 294  *
 295  *
 296  * a pointer to the filter's command line parser
 297  *
 298  * If this optional function pointer is not NULL, any filter options are passed
 299  * from the main propgram to this command line parser once at application
 300  * startup. The command line parser should check its command line options given
 301  * by \a argc and \a argv and abort on errors. On success, it should return a
 302  * pointer to the filter-specific configuration data determined by \a argc and
 303  * \a argv.
 304  */
 305 void *(*parse_config)(int argc, char **argv);
 306 };
 307 /** \cond */
 308 extern struct filter filters[];
 309 #define DECLARE_EXTERN_FILTER_INIT(name) \
 310         extern void name ## _init(struct filter *f)
 311
 312 #define FILTER_INIT(filter) { \
 313         .name = #filter, \
 314         .init = filter ## _init, \
 315         .parse_config = NULL, \
 316         .print_help = NULL \
 317 },
 318
 319 /* filters that are always present */
 320 DECLARE_EXTERN_FILTER_INIT(wav);
 321 /* wav is always the first filter */
 322 #define WAV_FILTER_NUM 0
 323 DECLARE_EXTERN_FILTER_INIT(compress);
 324
 325 /* next the optional filters */
 326 #ifdef HAVE_MAD
 327 DECLARE_EXTERN_FILTER_INIT(mp3dec);
 328 #define MP3DEC_FILTER FILTER_INIT(mp3dec)
 329 #else
 330 #define MP3DEC_FILTER
 331 #endif
 332
 333 #ifdef HAVE_OGGVORBIS
 334 DECLARE_EXTERN_FILTER_INIT(oggdec);
 335 #define OGGDEC_FILTER FILTER_INIT(oggdec)
 336 #else
 337 #define OGGDEC_FILTER
 338 #endif
 339
 340 /*
 341  * a macro that defines an array of all available filters
 342  */
 343 #define DEFINE_FILTER_ARRAY(fa) struct filter fa[] = { \
 344         FILTER_INIT(wav) \
 345         FILTER_INIT(compress) \
 346         MP3DEC_FILTER \
 347         OGGDEC_FILTER \
 348         { .name = NULL } };
 349 /** \endcond */