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 15 /* Do not include video here */ 00028 #define MAX_FORMAT 32 /* 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 int srcfmt; /*!< Source format (note: bit position, 00074 converted to index during registration) */ 00075 int 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 plc_samples; /* Unused. Here for ABI purposes */ 00109 int useplc; /* Unused. Here for ABI purposes */ 00110 int native_plc; /*!< true if the translator can do native plc */ 00111 00112 struct ast_module *module; /* opaque reference to the parent module */ 00113 00114 int cost; /*!< Cost in milliseconds for encoding/decoding 1 second of sound */ 00115 int active; /*!< Whether this translator should be used or not */ 00116 AST_LIST_ENTRY(ast_translator) list; /*!< link field */ 00117 }; 00118 00119 /*! \brief 00120 * Default structure for translators, with the basic fields and buffers, 00121 * all allocated as part of the same chunk of memory. The buffer is 00122 * preceded by \ref AST_FRIENDLY_OFFSET bytes in front of the user portion. 00123 * 'buf' points right after this space. 00124 * 00125 * *_framein() routines operate in two ways: 00126 * 1. some convert on the fly and place the data directly in outbuf; 00127 * in this case 'samples' and 'datalen' contain the number of samples 00128 * and number of bytes available in the buffer. 00129 * In this case we can use a generic *_frameout() routine that simply 00130 * takes whatever is there and places it into the output frame. 00131 * 2. others simply store the (unconverted) samples into a working 00132 * buffer, and leave the conversion task to *_frameout(). 00133 * In this case, the intermediate buffer must be in the private 00134 * descriptor, 'datalen' is left to 0, while 'samples' is still 00135 * updated with the number of samples received. 00136 */ 00137 struct ast_trans_pvt { 00138 struct ast_translator *t; 00139 struct ast_frame f; /*!< used in frameout */ 00140 int samples; /*!< samples available in outbuf */ 00141 /*! \brief actual space used in outbuf */ 00142 int datalen; 00143 void *pvt; /*!< more private data, if any */ 00144 union { 00145 char *c; /*!< the useful portion of the buffer */ 00146 unsigned char *uc; /*!< the useful portion of the buffer */ 00147 int16_t *i16; 00148 uint8_t *ui8; 00149 } outbuf; 00150 plc_state_t *plc; /*!< optional plc pointer */ 00151 struct ast_trans_pvt *next; /*!< next in translator chain */ 00152 struct timeval nextin; 00153 struct timeval nextout; 00154 unsigned int destroy:1; 00155 }; 00156 00157 /*! \brief generic frameout function */ 00158 struct ast_frame *ast_trans_frameout(struct ast_trans_pvt *pvt, 00159 int datalen, int samples); 00160 00161 struct ast_trans_pvt; 00162 00163 /*! 00164 * \brief Register a translator 00165 * This registers a codec translator with asterisk 00166 * \param t populated ast_translator structure 00167 * \param module handle to the module that owns this translator 00168 * \return 0 on success, -1 on failure 00169 */ 00170 int __ast_register_translator(struct ast_translator *t, struct ast_module *module); 00171 00172 /*! \brief See \ref __ast_register_translator() */ 00173 #define ast_register_translator(t) __ast_register_translator(t, ast_module_info->self) 00174 00175 /*! 00176 * \brief Unregister a translator 00177 * Unregisters the given tranlator 00178 * \param t translator to unregister 00179 * \return 0 on success, -1 on failure 00180 */ 00181 int ast_unregister_translator(struct ast_translator *t); 00182 00183 /*! 00184 * \brief Activate a previously deactivated translator 00185 * \param t translator to activate 00186 * \return nothing 00187 * 00188 * Enables the specified translator for use. 00189 */ 00190 void ast_translator_activate(struct ast_translator *t); 00191 00192 /*! 00193 * \brief Deactivate a translator 00194 * \param t translator to deactivate 00195 * \return nothing 00196 * 00197 * Disables the specified translator from being used. 00198 */ 00199 void ast_translator_deactivate(struct ast_translator *t); 00200 00201 /*! 00202 * \brief Chooses the best translation path 00203 * 00204 * Given a list of sources, and a designed destination format, which should 00205 * I choose? 00206 * \return Returns 0 on success, -1 if no path could be found. 00207 * \note Modifies dests and srcs in place 00208 */ 00209 int ast_translator_best_choice(int *dsts, int *srcs); 00210 00211 /*! 00212 * \brief Builds a translator path 00213 * Build a path (possibly NULL) from source to dest 00214 * \param dest destination format 00215 * \param source source format 00216 * \return ast_trans_pvt on success, NULL on failure 00217 * */ 00218 struct ast_trans_pvt *ast_translator_build_path(int dest, int source); 00219 00220 /*! 00221 * \brief Frees a translator path 00222 * Frees the given translator path structure 00223 * \param tr translator path to get rid of 00224 */ 00225 void ast_translator_free_path(struct ast_trans_pvt *tr); 00226 00227 /*! 00228 * \brief translates one or more frames 00229 * Apply an input frame into the translator and receive zero or one output frames. Consume 00230 * determines whether the original frame should be freed 00231 * \param tr translator structure to use for translation 00232 * \param f frame to translate 00233 * \param consume Whether or not to free the original frame 00234 * \return an ast_frame of the new translation format on success, NULL on failure 00235 */ 00236 struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume); 00237 00238 /*! 00239 * \brief Returns the number of steps required to convert from 'src' to 'dest'. 00240 * \param dest destination format 00241 * \param src source format 00242 * \return the number of translation steps required, or -1 if no path is available 00243 */ 00244 unsigned int ast_translate_path_steps(unsigned int dest, unsigned int src); 00245 00246 /*! 00247 * \brief Mask off unavailable formats from a format bitmask 00248 * \param dest possible destination formats 00249 * \param src source formats 00250 * \return the destination formats that are available in the source or translatable 00251 * 00252 * The result will include all formats from 'dest' that are either present 00253 * in 'src' or translatable from a format present in 'src'. 00254 * 00255 * \note Only a single audio format and a single video format can be 00256 * present in 'src', or the function will produce unexpected results. 00257 */ 00258 unsigned int ast_translate_available_formats(unsigned int dest, unsigned int src); 00259 00260 /*! 00261 * \brief Hint that a frame from a translator has been freed 00262 * 00263 * This is sort of a hack. This function gets called when ast_frame_free() gets 00264 * called on a frame that has the AST_FRFLAG_FROM_TRANSLATOR flag set. This is 00265 * because it is possible for a translation path to be destroyed while a frame 00266 * from a translator is still in use. Specifically, this happens if a masquerade 00267 * happens after a call to ast_read() but before the frame is done being processed, 00268 * since the frame processing is generally done without the channel lock held. 00269 * 00270 * \return nothing 00271 */ 00272 void ast_translate_frame_freed(struct ast_frame *fr); 00273 00274 #if defined(__cplusplus) || defined(c_plusplus) 00275 } 00276 #endif 00277 00278 #endif /* _ASTERISK_TRANSLATE_H */