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