Wed Apr 6 11:29:48 2011

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  * \ref translate.c
00022  */
00023 
00024 #ifndef _ASTERISK_TRANSLATE_H
00025 #define _ASTERISK_TRANSLATE_H
00026 
00027 #define MAX_AUDIO_FORMAT 47 /* Do not include video here */
00028 #define MAX_FORMAT 64   /* Do include video here */
00029 
00030 #if defined(__cplusplus) || defined(c_plusplus)
00031 extern "C" {
00032 #endif
00033 
00034 #if 1 /* need lots of stuff... */
00035 #include "asterisk/frame.h"
00036 #include "asterisk/plc.h"
00037 #include "asterisk/linkedlists.h"
00038 // XXX #include "asterisk/module.h"
00039 #endif
00040 
00041 struct ast_trans_pvt;   /* declared below */
00042 
00043 /*! \brief
00044  * Descriptor of a translator. 
00045  *
00046  * Name, callbacks, and various options
00047  * related to run-time operation (size of buffers, auxiliary
00048  * descriptors, etc).
00049  *
00050  * A codec registers itself by filling the relevant fields
00051  * of a structure and passing it as an argument to
00052  * ast_register_translator(). The structure should not be
00053  * modified after a successful registration, and its address
00054  * must be used as an argument to ast_unregister_translator().
00055  *
00056  * As a minimum, a translator should supply name, srcfmt and dstfmt,
00057  * the required buf_size (in bytes) and buffer_samples (in samples),
00058  * and a few callbacks (framein, frameout, sample).
00059  * The outbuf is automatically prepended by AST_FRIENDLY_OFFSET
00060  * spare bytes so generic routines can place data in there.
00061  *
00062  * Note, the translator is not supposed to do any memory allocation
00063  * or deallocation, nor any locking, because all of this is done in
00064  * the generic code.
00065  *
00066  * Translators using generic plc (packet loss concealment) should
00067  * supply a non-zero plc_samples indicating the size (in samples)
00068  * of artificially generated frames and incoming data.
00069  * Generic plc is only available for dstfmt = SLINEAR
00070  */
00071 struct ast_translator {
00072    const char name[80];                   /*!< Name of translator */
00073    format_t srcfmt;                       /*!< Source format (note: bit position,
00074                                            *   converted to index during registration) */
00075    format_t dstfmt;                       /*!< Destination format (note: bit position,
00076                                            *   converted to index during registration) */
00077 
00078    int (*newpvt)(struct ast_trans_pvt *); /*!< initialize private data 
00079                                             *   associated with the translator */
00080 
00081    int (*framein)(struct ast_trans_pvt *pvt, struct ast_frame *in);
00082                                           /*!< Input frame callback. Store 
00083                                            *   (and possibly convert) input frame. */
00084 
00085    struct ast_frame * (*frameout)(struct ast_trans_pvt *pvt);
00086                                           /*!< Output frame callback. Generate a frame 
00087                                            *   with outbuf content. */
00088 
00089    void (*destroy)(struct ast_trans_pvt *pvt);
00090                                           /*!< cleanup private data, if needed 
00091                                            *   (often unnecessary). */
00092 
00093    struct ast_frame * (*sample)(void);    /*!< Generate an example frame */
00094 
00095    /*!\brief size of outbuf, in samples. Leave it 0 if you want the framein
00096     * callback deal with the frame. Set it appropriately if you
00097     * want the code to checks if the incoming frame fits the
00098     * outbuf (this is e.g. required for plc).
00099     */
00100    int buffer_samples;                    /*< size of outbuf, in samples */
00101 
00102    /*! \brief size of outbuf, in bytes. Mandatory. The wrapper code will also
00103     * allocate an AST_FRIENDLY_OFFSET space before.
00104     */
00105    int buf_size;
00106 
00107    int desc_size;                         /*!< size of private descriptor in pvt->pvt, if any */
00108    int native_plc;                        /*!< true if the translator can do native plc */
00109 
00110    struct ast_module *module;             /*!< opaque reference to the parent module */
00111 
00112    int cost;                              /*!< Cost in milliseconds for encoding/decoding 1 second of sound */
00113    int active;                            /*!< Whether this translator should be used or not */
00114    AST_LIST_ENTRY(ast_translator) list;   /*!< link field */
00115 };
00116 
00117 /*! \brief
00118  * Default structure for translators, with the basic fields and buffers,
00119  * all allocated as part of the same chunk of memory. The buffer is
00120  * preceded by \ref AST_FRIENDLY_OFFSET bytes in front of the user portion.
00121  * 'buf' points right after this space.
00122  *
00123  * *_framein() routines operate in two ways:
00124  * 1. some convert on the fly and place the data directly in outbuf;
00125  *    in this case 'samples' and 'datalen' contain the number of samples
00126  *    and number of bytes available in the buffer.
00127  *    In this case we can use a generic *_frameout() routine that simply
00128  *    takes whatever is there and places it into the output frame.
00129  * 2. others simply store the (unconverted) samples into a working
00130  *    buffer, and leave the conversion task to *_frameout().
00131  *    In this case, the intermediate buffer must be in the private
00132  *    descriptor, 'datalen' is left to 0, while 'samples' is still
00133  *    updated with the number of samples received.
00134  */
00135 struct ast_trans_pvt {
00136    struct ast_translator *t;
00137    struct ast_frame f;         /*!< used in frameout */
00138    int samples;                /*!< samples available in outbuf */
00139    /*! \brief actual space used in outbuf */
00140    int datalen;
00141    void *pvt;                  /*!< more private data, if any */
00142    union {
00143       char *c;                /*!< the useful portion of the buffer */
00144       unsigned char *uc;      /*!< the useful portion of the buffer */
00145       int16_t *i16;
00146       uint8_t *ui8;
00147    } outbuf; 
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 
00169 /*! \brief See \ref __ast_register_translator() */
00170 #define ast_register_translator(t) __ast_register_translator(t, ast_module_info->self)
00171 
00172 /*!
00173  * \brief Unregister a translator
00174  * Unregisters the given tranlator
00175  * \param t translator to unregister
00176  * \return 0 on success, -1 on failure
00177  */
00178 int ast_unregister_translator(struct ast_translator *t);
00179 
00180 /*!
00181  * \brief Activate a previously deactivated translator
00182  * \param t translator to activate
00183  * \return nothing
00184  *
00185  * Enables the specified translator for use.
00186  */
00187 void ast_translator_activate(struct ast_translator *t);
00188 
00189 /*!
00190  * \brief Deactivate a translator
00191  * \param t translator to deactivate
00192  * \return nothing
00193  *
00194  * Disables the specified translator from being used.
00195  */
00196 void ast_translator_deactivate(struct ast_translator *t);
00197 
00198 /*!
00199  * \brief Chooses the best translation path
00200  *
00201  * Given a list of sources, and a designed destination format, which should
00202  * I choose? 
00203  * \return Returns 0 on success, -1 if no path could be found.  
00204  * \note Modifies dests and srcs in place 
00205  */
00206 format_t ast_translator_best_choice(format_t *dsts, format_t *srcs);
00207 
00208 /*! 
00209  * \brief Builds a translator path
00210  * Build a path (possibly NULL) from source to dest 
00211  * \param dest destination format
00212  * \param source source format
00213  * \return ast_trans_pvt on success, NULL on failure
00214  * */
00215 struct ast_trans_pvt *ast_translator_build_path(format_t dest, format_t source);
00216 
00217 /*!
00218  * \brief Frees a translator path
00219  * Frees the given translator path structure
00220  * \param tr translator path to get rid of
00221  */
00222 void ast_translator_free_path(struct ast_trans_pvt *tr);
00223 
00224 /*!
00225  * \brief translates one or more frames
00226  * Apply an input frame into the translator and receive zero or one output frames.  Consume
00227  * determines whether the original frame should be freed
00228  * \param tr translator structure to use for translation
00229  * \param f frame to translate
00230  * \param consume Whether or not to free the original frame
00231  * \return an ast_frame of the new translation format on success, NULL on failure
00232  */
00233 struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);
00234 
00235 /*!
00236  * \brief Returns the number of steps required to convert from 'src' to 'dest'.
00237  * \param dest destination format
00238  * \param src source format
00239  * \return the number of translation steps required, or -1 if no path is available
00240  */
00241 unsigned int ast_translate_path_steps(format_t dest, format_t src);
00242 
00243 /*!
00244  * \brief Mask off unavailable formats from a format bitmask
00245  * \param dest possible destination formats
00246  * \param src source formats
00247  * \return the destination formats that are available in the source or translatable
00248  *
00249  * The result will include all formats from 'dest' that are either present
00250  * in 'src' or translatable from a format present in 'src'.
00251  *
00252  * \note Only a single audio format and a single video format can be
00253  * present in 'src', or the function will produce unexpected results.
00254  */
00255 format_t ast_translate_available_formats(format_t dest, format_t src);
00256 
00257 /*!
00258  * \brief Puts a string representation of the translation path into outbuf
00259  * \param translator structure containing the translation path
00260  * \param ast_str output buffer
00261  * \retval on success pointer to beginning of outbuf. on failure "".
00262  */
00263 const char *ast_translate_path_to_str(struct ast_trans_pvt *t, struct ast_str **str);
00264 
00265 #if defined(__cplusplus) || defined(c_plusplus)
00266 }
00267 #endif
00268 
00269 #endif /* _ASTERISK_TRANSLATE_H */

Generated on Wed Apr 6 11:29:48 2011 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7