include/asterisk/translate.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 1999 - 2006, Digium, Inc.
   5  *
   6  * Mark Spencer <markster@digium.com>
   7  *
   8  * See http://www.asterisk.org for more information about
   9  * the Asterisk project. Please do not directly contact
  10  * any of the maintainers of this project for assistance;
  11  * the project provides a web site, mailing lists and IRC
  12  * channels for your use.
  13  *
  14  * This program is free software, distributed under the terms of
  15  * the GNU General Public License Version 2. See the LICENSE file
  16  * at the top of the source tree.
  17  */
  18
  19 /*! \file
  20  * \brief Support for translation of data formats.
  21  * \ref translate.c
  22  */
  23
  24 #ifndef _ASTERISK_TRANSLATE_H
  25 #define _ASTERISK_TRANSLATE_H
  26
  27 //#define MAX_FORMAT 15 /* Do not include video here */
  28 #define MAX_FORMAT 32   /* Do include video here */
  29
  30 #if defined(__cplusplus) || defined(c_plusplus)
  31 extern "C" {
  32 #endif
  33
  34 #if 1   /* need lots of stuff... */
  35 #include "asterisk/frame.h"
  36 #include "asterisk/plc.h"
  37 #include "asterisk/linkedlists.h"
  38 // XXX #include "asterisk/module.h"
  39 #endif
  40
  41 struct ast_trans_pvt;   /* declared below */
  42
  43 /*! \brief
  44  * Descriptor of a translator.
  45  *
  46  * Name, callbacks, and various options
  47  * related to run-time operation (size of buffers, auxiliary
  48  * descriptors, etc).
  49  *
  50  * A codec registers itself by filling the relevant fields
  51  * of a structure and passing it as an argument to
  52  * ast_register_translator(). The structure should not be
  53  * modified after a successful registration, and its address
  54  * must be used as an argument to ast_unregister_translator().
  55  *
  56  * As a minimum, a translator should supply name, srcfmt and dstfmt,
  57  * the required buf_size (in bytes) and buffer_samples (in samples),
  58  * and a few callbacks (framein, frameout, sample).
  59  * The outbuf is automatically prepended by AST_FRIENDLY_OFFSET
  60  * spare bytes so generic routines can place data in there.
  61  *
  62  * Note, the translator is not supposed to do any memory allocation
  63  * or deallocation, nor any locking, because all of this is done in
  64  * the generic code.
  65  *
  66  * Translators using generic plc (packet loss concealment) should
  67  * supply a non-zero plc_samples indicating the size (in samples)
  68  * of artificially generated frames and incoming data.
  69  * Generic plc is only available for dstfmt = SLINEAR
  70  */
  71 struct ast_translator {
  72         const char name[80];            /*!< Name of translator */
  73         int srcfmt;                     /*!< Source format (note: bit position,
  74                                           converted to index during registration) */
  75         int dstfmt;                     /*!< Destination format (note: bit position,
  76                                           converted to index during registration) */
  77
  78         int (*newpvt)(struct ast_trans_pvt *); /*!< initialize private data
  79                                         associated with the translator */
  80
  81         int (*framein)(struct ast_trans_pvt *pvt, struct ast_frame *in);
  82                                         /*!< Input frame callback. Store
  83                                              (and possibly convert) input frame. */
  84
  85         struct ast_frame * (*frameout)(struct ast_trans_pvt *pvt);
  86                                         /*!< Output frame callback. Generate a frame
  87                                             with outbuf content. */
  88
  89         void (*destroy)(struct ast_trans_pvt *pvt);
  90                                         /*!< cleanup private data, if needed
  91                                                 (often unnecessary). */
  92
  93         struct ast_frame * (*sample)(void);     /*!< Generate an example frame */
  94
  95         /*! \brief size of outbuf, in samples. Leave it 0 if you want the framein
  96          * callback deal with the frame. Set it appropriately if you
  97          * want the code to checks if the incoming frame fits the
  98          * outbuf (this is e.g. required for plc).
  99          */
 100         int buffer_samples;     /*< size of outbuf, in samples */
 101
 102         /*! \brief size of outbuf, in bytes. Mandatory. The wrapper code will also
 103          * allocate an AST_FRIENDLY_OFFSET space before.
 104          */
 105         int buf_size;
 106
 107         int desc_size;                  /*!< size of private descriptor in pvt->pvt, if any */
 108         int plc_samples;                /*!< set to the plc block size if used, 0 otherwise */
 109         int useplc;                     /*!< current status of plc, changed at runtime */
 110         int native_plc;                 /*!< true if the translator can do native plc */
 111
 112         struct ast_module *module;      /* opaque reference to the parent module */
 113
 114         int cost;                       /*!< Cost in milliseconds for encoding/decoding 1 second of sound */
 115         int active;                     /*!< Whether this translator should be used or not */
 116         AST_LIST_ENTRY(ast_translator) list;    /*!< link field */
 117 };
 118
 119 /*! \brief
 120  * Default structure for translators, with the basic fields and buffers,
 121  * all allocated as part of the same chunk of memory. The buffer is
 122  * preceded by \ref AST_FRIENDLY_OFFSET bytes in front of the user portion.
 123  * 'buf' points right after this space.
 124  *
 125  * *_framein() routines operate in two ways:
 126  * 1. some convert on the fly and place the data directly in outbuf;
 127  *    in this case 'samples' and 'datalen' contain the number of samples
 128  *    and number of bytes available in the buffer.
 129  *    In this case we can use a generic *_frameout() routine that simply
 130  *    takes whatever is there and places it into the output frame.
 131  * 2. others simply store the (unconverted) samples into a working
 132  *    buffer, and leave the conversion task to *_frameout().
 133  *    In this case, the intermediate buffer must be in the private
 134  *    descriptor, 'datalen' is left to 0, while 'samples' is still
 135  *    updated with the number of samples received.
 136  */
 137 struct ast_trans_pvt {
 138         struct ast_translator *t;
 139         struct ast_frame f;     /*!< used in frameout */
 140         int samples;            /*!< samples available in outbuf */
 141         int datalen;            /*!< actual space used in outbuf */
 142         void *pvt;              /*!< more private data, if any */
 143         char *outbuf;           /*!< the useful portion of the buffer */
 144         plc_state_t *plc;       /*!< optional plc pointer */
 145         struct ast_trans_pvt *next;     /*!< next in translator chain */
 146         struct timeval nextin;
 147         struct timeval nextout;
 148 };
 149
 150 /*! \brief generic frameout function */
 151 struct ast_frame *ast_trans_frameout(struct ast_trans_pvt *pvt,
 152         int datalen, int samples);
 153
 154 struct ast_trans_pvt;
 155
 156 /*!
 157  * \brief Register a translator
 158  * This registers a codec translator with asterisk
 159  * \param t populated ast_translator structure
 160  * \param module handle to the module that owns this translator
 161  * \return 0 on success, -1 on failure
 162  */
 163 int __ast_register_translator(struct ast_translator *t, struct ast_module *module);
 164
 165 /*! \brief See \ref __ast_register_translator() */
 166 #define ast_register_translator(t) __ast_register_translator(t, ast_module_info->self)
 167
 168 /*!
 169  * \brief Unregister a translator
 170  * Unregisters the given tranlator
 171  * \param t translator to unregister
 172  * \return 0 on success, -1 on failure
 173  */
 174 int ast_unregister_translator(struct ast_translator *t);
 175
 176 /*!
 177  * \brief Activate a previously deactivated translator
 178  * \param t translator to activate
 179  * \return nothing
 180  *
 181  * Enables the specified translator for use.
 182  */
 183 void ast_translator_activate(struct ast_translator *t);
 184
 185 /*!
 186  * \brief Deactivate a translator
 187  * \param t translator to deactivate
 188  * \return nothing
 189  *
 190  * Disables the specified translator from being used.
 191  */
 192 void ast_translator_deactivate(struct ast_translator *t);
 193
 194 /*!
 195  * \brief Chooses the best translation path
 196  *
 197  * Given a list of sources, and a designed destination format, which should
 198  * I choose?
 199  * \return Returns 0 on success, -1 if no path could be found.
 200  * \note Modifies dests and srcs in place
 201  */
 202 int ast_translator_best_choice(int *dsts, int *srcs);
 203
 204 /*!
 205  * \brief Builds a translator path
 206  * Build a path (possibly NULL) from source to dest
 207  * \param dest destination format
 208  * \param source source format
 209  * \return ast_trans_pvt on success, NULL on failure
 210  * */
 211 struct ast_trans_pvt *ast_translator_build_path(int dest, int source);
 212
 213 /*!
 214  * \brief Frees a translator path
 215  * Frees the given translator path structure
 216  * \param tr translator path to get rid of
 217  */
 218 void ast_translator_free_path(struct ast_trans_pvt *tr);
 219
 220 /*!
 221  * \brief translates one or more frames
 222  * Apply an input frame into the translator and receive zero or one output frames.  Consume
 223  * determines whether the original frame should be freed
 224  * \param tr translator structure to use for translation
 225  * \param f frame to translate
 226  * \param consume Whether or not to free the original frame
 227  * \return an ast_frame of the new translation format on success, NULL on failure
 228  */
 229 struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);
 230
 231 /*!
 232  * \brief Returns the number of steps required to convert from 'src' to 'dest'.
 233  * \param dest destination format
 234  * \param src source format
 235  * \return the number of translation steps required, or -1 if no path is available
 236  */
 237 unsigned int ast_translate_path_steps(unsigned int dest, unsigned int src);
 238
 239 /*!
 240  * \brief Mask off unavailable formats from a format bitmask
 241  * \param dest possible destination formats
 242  * \param src source formats
 243  * \return the destination formats that are available in the source or translatable
 244  *
 245  * The result will include all formats from 'dest' that are either present
 246  * in 'src' or translatable from a format present in 'src'.
 247  *
 248  * \note Only a single audio format and a single video format can be
 249  * present in 'src', or the function will produce unexpected results.
 250  */
 251 unsigned int ast_translate_available_formats(unsigned int dest, unsigned int src);
 252
 253 #if defined(__cplusplus) || defined(c_plusplus)
 254 }
 255 #endif
 256
 257 #endif /* _ASTERISK_TRANSLATE_H */