8a5ac2106a0b8bb7b06db517384282197e4a9226
[asterisk/asterisk.git] / 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_AUDIO_FORMAT 47 /* Do not include video here */
28 #define MAX_FORMAT 64   /* 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         format_t srcfmt;                       /*!< Source format (note: bit position,
74                                                 *   converted to index during registration) */
75         format_t 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         /*! \brief actual space used in outbuf */
142         int datalen;
143         void *pvt;                  /*!< more private data, if any */
144         union {
145                 char *c;                /*!< the useful portion of the buffer */
146                 unsigned char *uc;      /*!< the useful portion of the buffer */
147                 int16_t *i16;
148                 uint8_t *ui8;
149         } outbuf; 
150         plc_state_t *plc;           /*!< optional plc pointer */
151         struct ast_trans_pvt *next; /*!< next in translator chain */
152         struct timeval nextin;
153         struct timeval nextout;
154 };
155
156 /*! \brief generic frameout function */
157 struct ast_frame *ast_trans_frameout(struct ast_trans_pvt *pvt,
158         int datalen, int samples);
159
160 struct ast_trans_pvt;
161
162 /*!
163  * \brief Register a translator
164  * This registers a codec translator with asterisk
165  * \param t populated ast_translator structure
166  * \param module handle to the module that owns this translator
167  * \return 0 on success, -1 on failure
168  */
169 int __ast_register_translator(struct ast_translator *t, struct ast_module *module);
170
171 /*! \brief See \ref __ast_register_translator() */
172 #define ast_register_translator(t) __ast_register_translator(t, ast_module_info->self)
173
174 /*!
175  * \brief Unregister a translator
176  * Unregisters the given tranlator
177  * \param t translator to unregister
178  * \return 0 on success, -1 on failure
179  */
180 int ast_unregister_translator(struct ast_translator *t);
181
182 /*!
183  * \brief Activate a previously deactivated translator
184  * \param t translator to activate
185  * \return nothing
186  *
187  * Enables the specified translator for use.
188  */
189 void ast_translator_activate(struct ast_translator *t);
190
191 /*!
192  * \brief Deactivate a translator
193  * \param t translator to deactivate
194  * \return nothing
195  *
196  * Disables the specified translator from being used.
197  */
198 void ast_translator_deactivate(struct ast_translator *t);
199
200 /*!
201  * \brief Chooses the best translation path
202  *
203  * Given a list of sources, and a designed destination format, which should
204  * I choose? 
205  * \return Returns 0 on success, -1 if no path could be found.  
206  * \note Modifies dests and srcs in place 
207  */
208 format_t ast_translator_best_choice(format_t *dsts, format_t *srcs);
209
210 /*! 
211  * \brief Builds a translator path
212  * Build a path (possibly NULL) from source to dest 
213  * \param dest destination format
214  * \param source source format
215  * \return ast_trans_pvt on success, NULL on failure
216  * */
217 struct ast_trans_pvt *ast_translator_build_path(format_t dest, format_t source);
218
219 /*!
220  * \brief Frees a translator path
221  * Frees the given translator path structure
222  * \param tr translator path to get rid of
223  */
224 void ast_translator_free_path(struct ast_trans_pvt *tr);
225
226 /*!
227  * \brief translates one or more frames
228  * Apply an input frame into the translator and receive zero or one output frames.  Consume
229  * determines whether the original frame should be freed
230  * \param tr translator structure to use for translation
231  * \param f frame to translate
232  * \param consume Whether or not to free the original frame
233  * \return an ast_frame of the new translation format on success, NULL on failure
234  */
235 struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);
236
237 /*!
238  * \brief Returns the number of steps required to convert from 'src' to 'dest'.
239  * \param dest destination format
240  * \param src source format
241  * \return the number of translation steps required, or -1 if no path is available
242  */
243 unsigned int ast_translate_path_steps(format_t dest, format_t src);
244
245 /*!
246  * \brief Mask off unavailable formats from a format bitmask
247  * \param dest possible destination formats
248  * \param src source formats
249  * \return the destination formats that are available in the source or translatable
250  *
251  * The result will include all formats from 'dest' that are either present
252  * in 'src' or translatable from a format present in 'src'.
253  *
254  * \note Only a single audio format and a single video format can be
255  * present in 'src', or the function will produce unexpected results.
256  */
257 format_t ast_translate_available_formats(format_t dest, format_t src);
258
259 #if defined(__cplusplus) || defined(c_plusplus)
260 }
261 #endif
262
263 #endif /* _ASTERISK_TRANSLATE_H */