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