Fri Apr 24 16:26:03 2009

Asterisk developer's documentation


translate.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2006, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Support for translation of data formats.
00021  */
00022 
00023 #ifndef _ASTERISK_TRANSLATE_H
00024 #define _ASTERISK_TRANSLATE_H
00025 
00026 #define MAX_AUDIO_FORMAT 15 /* Do not include video here */
00027 #define MAX_FORMAT 32   /* Do include video here */
00028 
00029 #if defined(__cplusplus) || defined(c_plusplus)
00030 extern "C" {
00031 #endif
00032 
00033 #if 1 /* need lots of stuff... */
00034 #include "asterisk/frame.h"
00035 #include "asterisk/plc.h"
00036 #include "asterisk/linkedlists.h"
00037 // XXX #include "asterisk/module.h"
00038 #endif
00039 
00040 struct ast_trans_pvt;   /* declared below */
00041 
00042 /*! \brief
00043  * Descriptor of a translator. Name, callbacks, and various options
00044  * related to run-time operation (size of buffers, auxiliary
00045  * descriptors, etc).
00046  *
00047  * A coded registers itself by filling the relevant fields
00048  * of a structure and passing it as an argument to
00049  * ast_register_translator(). The structure should not be
00050  * modified after a successful registration, and its address
00051  * must be used as an argument to ast_unregister_translator().
00052  *
00053  * As a minimum, a translator should supply name, srcfmt and dstfmt,
00054  * the required buf_size (in bytes) and buffer_samples (in samples),
00055  * and a few callbacks (framein, frameout, sample).
00056  * The outbuf is automatically prepended by AST_FRIENDLY_OFFSET
00057  * spare bytes so generic routines can place data in there.
00058  *
00059  * Note, the translator is not supposed to do any memory allocation
00060  * or deallocation, nor any locking, because all of this is done in
00061  * the generic code.
00062  *
00063  * Translators using generic plc (packet loss concealment) should
00064  * supply a non-zero plc_samples indicating the size (in samples)
00065  * of artificially generated frames and incoming data.
00066  * Generic plc is only available for dstfmt = SLINEAR
00067  */
00068 struct ast_translator {
00069    const char name[80];    /*!< Name of translator */
00070    int srcfmt;       /*!< Source format (note: bit position,
00071                  converted to index during registration) */
00072    int dstfmt;       /*!< Destination format (note: bit position,
00073                  converted to index during registration) */
00074 
00075    int (*newpvt)(struct ast_trans_pvt *); /*!< initialize private data 
00076                associated with the translator */
00077 
00078    int (*framein)(struct ast_trans_pvt *pvt, struct ast_frame *in);
00079                /*!< Input frame callback. Store 
00080                     (and possibly convert) input frame. */
00081 
00082    struct ast_frame * (*frameout)(struct ast_trans_pvt *pvt);
00083                /*!< Output frame callback. Generate a frame 
00084                    with outbuf content. */
00085 
00086    void (*destroy)(struct ast_trans_pvt *pvt);
00087                /*!< cleanup private data, if needed 
00088                   (often unnecessary). */
00089 
00090    struct ast_frame * (*sample)(void); /*!< Generate an example frame */
00091 
00092    /*! \brief size of outbuf, in samples. Leave it 0 if you want the framein
00093     * callback deal with the frame. Set it appropriately if you
00094     * want the code to checks if the incoming frame fits the
00095     * outbuf (this is e.g. required for plc).
00096     */
00097    int buffer_samples;  /*< size of outbuf, in samples */
00098 
00099    /*! \brief size of outbuf, in bytes. Mandatory. The wrapper code will also
00100     * allocate an AST_FRIENDLY_OFFSET space before.
00101     */
00102    int buf_size;
00103 
00104    int desc_size;       /*!< size of private descriptor in pvt->pvt, if any */
00105    int plc_samples;     /*!< set to the plc block size if used, 0 otherwise */
00106    int useplc;       /*!< current status of plc, changed at runtime */
00107    int native_plc;         /*!< true if the translator can do native plc */
00108 
00109    struct ast_module *module; /* opaque reference to the parent module */
00110 
00111    int cost;         /*!< Cost in milliseconds for encoding/decoding 1 second of sound */
00112    int active;       /*!< Whether this translator should be used or not */
00113    AST_LIST_ENTRY(ast_translator) list;   /*!< link field */
00114 };
00115 
00116 /*! \brief
00117  * Default structure for translators, with the basic fields and buffers,
00118  * all allocated as part of the same chunk of memory. The buffer is
00119  * preceded by AST_FRIENDLY_OFFSET bytes in front of the user portion.
00120  * 'buf' points right after this space.
00121  *
00122  * *_framein() routines operate in two ways:
00123  * 1. some convert on the fly and place the data directly in outbuf;
00124  *    in this case 'samples' and 'datalen' contain the number of samples
00125  *    and number of bytes available in the buffer.
00126  *    In this case we can use a generic *_frameout() routine that simply
00127  *    takes whatever is there and places it into the output frame.
00128  * 2. others simply store the (unconverted) samples into a working
00129  *    buffer, and leave the conversion task to *_frameout().
00130  *    In this case, the intermediate buffer must be in the private
00131  *    descriptor, 'datalen' is left to 0, while 'samples' is still
00132  *    updated with the number of samples received.
00133  */
00134 struct ast_trans_pvt {
00135    struct ast_translator *t;
00136    struct ast_frame f;  /*!< used in frameout */
00137    int samples;      /*!< samples available in outbuf */
00138    /*! 
00139     * \brief actual space used in outbuf
00140     *
00141     * Also, for the sake of ABI compatability, a magic value of -1 in this
00142     * field means that the pvt has been requested to be destroyed, but is
00143     * pending destruction until ast_translate_frame_freed() gets called. 
00144     */
00145    int datalen;
00146    void *pvt;     /*!< more private data, if any */
00147    char *outbuf;     /*!< the useful portion of the buffer */
00148    plc_state_t *plc; /*!< optional plc pointer */
00149    struct ast_trans_pvt *next;   /*!< next in translator chain */
00150    struct timeval nextin;
00151    struct timeval nextout;
00152 };
00153 
00154 /*! \brief generic frameout function */
00155 struct ast_frame *ast_trans_frameout(struct ast_trans_pvt *pvt,
00156         int datalen, int samples);
00157 
00158 struct ast_trans_pvt;
00159 
00160 /*!
00161  * \brief Register a translator
00162  * This registers a codec translator with asterisk
00163  * \param t populated ast_translator structure
00164  * \param module handle to the module that owns this translator
00165  * \return 0 on success, -1 on failure
00166  */
00167 int __ast_register_translator(struct ast_translator *t, struct ast_module *module);
00168 #define ast_register_translator(t) __ast_register_translator(t, ast_module_info->self)
00169 
00170 /*!
00171  * \brief Unregister a translator
00172  * Unregisters the given tranlator
00173  * \param t translator to unregister
00174  * \return 0 on success, -1 on failure
00175  */
00176 int ast_unregister_translator(struct ast_translator *t);
00177 
00178 /*!
00179  * \brief Activate a previously deactivated translator
00180  * \param t translator to activate
00181  * \return nothing
00182  *
00183  * Enables the specified translator for use.
00184  */
00185 void ast_translator_activate(struct ast_translator *t);
00186 
00187 /*!
00188  * \brief Deactivate a translator
00189  * \param t translator to deactivate
00190  * \return nothing
00191  *
00192  * Disables the specified translator from being used.
00193  */
00194 void ast_translator_deactivate(struct ast_translator *t);
00195 
00196 /*!
00197  * \brief Chooses the best translation path
00198  *
00199  * Given a list of sources, and a designed destination format, which should
00200  * I choose? 
00201  * \return Returns 0 on success, -1 if no path could be found.  
00202  * \note Modifies dests and srcs in place 
00203  */
00204 int ast_translator_best_choice(int *dsts, int *srcs);
00205 
00206 /*! 
00207  * \brief Builds a translator path
00208  * Build a path (possibly NULL) from source to dest 
00209  * \param dest destination format
00210  * \param source source format
00211  * \return ast_trans_pvt on success, NULL on failure
00212  * */
00213 struct ast_trans_pvt *ast_translator_build_path(int dest, int source);
00214 
00215 /*!
00216  * \brief Frees a translator path
00217  * Frees the given translator path structure
00218  * \param tr translator path to get rid of
00219  */
00220 void ast_translator_free_path(struct ast_trans_pvt *tr);
00221 
00222 /*!
00223  * \brief translates one or more frames
00224  * Apply an input frame into the translator and receive zero or one output frames.  Consume
00225  * determines whether the original frame should be freed
00226  * \param tr translator structure to use for translation
00227  * \param f frame to translate
00228  * \param consume Whether or not to free the original frame
00229  * \return an ast_frame of the new translation format on success, NULL on failure
00230  */
00231 struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);
00232 
00233 /*!
00234  * \brief Returns the number of steps required to convert from 'src' to 'dest'.
00235  * \param dest destination format
00236  * \param src source format
00237  * \return the number of translation steps required, or -1 if no path is available
00238  */
00239 unsigned int ast_translate_path_steps(unsigned int dest, unsigned int src);
00240 
00241 /*!
00242  * \brief Mask off unavailable formats from a format bitmask
00243  * \param dest possible destination formats
00244  * \param src source formats
00245  * \return the destination formats that are available in the source or translatable
00246  *
00247  * The result will include all formats from 'dest' that are either present
00248  * in 'src' or translatable from a format present in 'src'.
00249  *
00250  * Note that only a single audio format and a single video format can be
00251  * present in 'src', or the function will produce unexpected results.
00252  */
00253 unsigned int ast_translate_available_formats(unsigned int dest, unsigned int src);
00254 
00255 /*!
00256  * \brief Hint that a frame from a translator has been freed
00257  *
00258  * This is sort of a hack.  This function gets called when ast_frame_free() gets
00259  * called on a frame that has the AST_FRFLAG_FROM_TRANSLATOR flag set.  This is
00260  * because it is possible for a translation path to be destroyed while a frame
00261  * from a translator is still in use.  Specifically, this happens if a masquerade
00262  * happens after a call to ast_read() but before the frame is done being processed, 
00263  * since the frame processing is generally done without the channel lock held.
00264  *
00265  * \return nothing
00266  */
00267 void ast_translate_frame_freed(struct ast_frame *fr);
00268 
00269 #if defined(__cplusplus) || defined(c_plusplus)
00270 }
00271 #endif
00272 
00273 #endif /* _ASTERISK_TRANSLATE_H */

Generated on Fri Apr 24 16:26:03 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7