d1431b3be0b3d0093d652fa07055f2bbd612f142
[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 32
27
28 #if defined(__cplusplus) || defined(c_plusplus)
29 extern "C" {
30 #endif
31
32 #if 1   /* need lots of stuff... */
33 #include "asterisk/frame.h"
34 #include "asterisk/plc.h"
35 #include "asterisk/linkedlists.h"
36 // XXX #include "asterisk/module.h"
37 #endif
38
39 struct ast_trans_pvt;   /* declared below */
40
41 /*!
42  * Descriptor of a translator. Name, callbacks, and various options
43  * related to run-time operation (size of buffers, auxiliary
44  * descriptors, etc).
45  * A coded registers itself by filling the relevant fields
46  * of a structure and passing it as an argument to
47  * ast_register_translator(). The structure should not be
48  * modified after a successful register(), and its address
49  * must be used as an argument to ast_unregister_translator().
50  *
51  * As a minimum, a translator should supply name, srcfmt and dstfmt,
52  * the required buf_size (in bytes) and buffer_samples (in samples),
53  * and a few callbacks (framein, frameout, sample).
54  * The outbuf is automatically prepended by AST_FRIENDLY_OFFSET
55  * spare bytes so generic routines can place data in there.
56  *
57  * Note, the translator is not supposed to do any memory allocation
58  * or deallocation, nor any locking, because all of this is done in
59  * the generic code.
60  *
61  * Translators using generic plc (packet loss concealment) should
62  * supply a non-zero plc_samples indicating the size (in samples)
63  * of artificially generated frames and incoming data.
64  * Generic plc is only available for dstfmt = SLINEAR
65  */
66 struct ast_translator {
67         const char name[80];            /*! Name of translator */
68         int srcfmt;                     /*! Source format (note: bit position,
69                                           converted to index during registration) */
70         int dstfmt;                     /*! Destination format (note: bit position,
71                                           converted to index during registration) */
72
73         /*! initialize private data associated with the translator */
74         void *(*newpvt)(struct ast_trans_pvt *);
75
76         /*! Input frame callback. Store (and possibly convert) input frame. */
77         int (*framein)(struct ast_trans_pvt *pvt, struct ast_frame *in);
78
79         /*! Output frame callback. Generate a frame with outbuf content. */
80         struct ast_frame * (*frameout)(struct ast_trans_pvt *pvt);
81
82         /*! cleanup private data, if needed (often unnecessary). */
83         void (*destroy)(struct ast_trans_pvt *pvt);
84
85         struct ast_frame * (*sample)(void);     /*! Generate an example frame */
86
87         /*! size of outbuf, in samples. Leave it 0 if you want the framein
88          * callback deal with the frame. Set it appropriately if you
89          * want the code to checks if the incoming frame fits the
90          * outbuf (this is e.g. required for plc).
91          */
92         int buffer_samples;     /* size of outbuf, in samples */
93
94         /*! size of outbuf, in bytes. Mandatory. The wrapper code will also
95          * allocate an AST_FRIENDLY_OFFSET space before.
96          */
97         int buf_size;
98
99         int desc_size;          /*! size of private descriptor in pvt->pvt, if any */
100         int plc_samples;        /* set to the plc block size if used, 0 otherwise */
101         int useplc;             /* current status of plc, changed at runtime */
102
103         void *module;           /* opaque reference to the parent module */
104
105         int cost;               /*! Cost in milliseconds for encoding/decoding 1 second of sound */
106         AST_LIST_ENTRY(ast_translator) list;    /*! link field */
107 };
108
109 /*
110  * Default structure for translators, with the basic fields and buffers,
111  * all allocated as part of the same chunk of memory. The buffer is
112  * preceded by AST_FRIENDLY_OFFSET bytes in front of the user portion.
113  * 'buf' points right after this space.
114  *
115  * *_framein() routines operate in two ways:
116  * 1. some convert on the fly and place the data directly in outbuf;
117  *    in this case 'samples' and 'datalen' contain the number of samples
118  *    and number of bytes available in the buffer.
119  *    In this case we can use a generic *_frameout() routine that simply
120  *    takes whatever is there and places it into the output frame.
121  * 2. others simply store the (unconverted) samples into a working
122  *    buffer, and leave the conversion task to *_frameout().
123  *    In this case, the intermediate buffer must be in the private
124  *    descriptor, 'datalen' is left to 0, while 'samples' is still
125  *    updated with the number of samples received.
126  */
127 struct ast_trans_pvt {
128         struct ast_translator *t;
129         struct ast_frame f;     /* used in frameout */
130         int samples;            /* samples available in outbuf */
131         int datalen;            /* actual space used in outbuf */
132         void *pvt;              /* more private data, if any */
133         char *outbuf;           /* the useful portion of the buffer */
134         plc_state_t *plc;       /* optional plc pointer */
135         struct ast_trans_pvt *next;     /* next in translator chain */
136         struct timeval nextin;
137         struct timeval nextout;
138 };
139
140 /* generic frameout function */
141 struct ast_frame *ast_trans_frameout(struct ast_trans_pvt *pvt,
142         int datalen, int samples);
143
144 struct ast_trans_pvt;
145
146 /*!
147  * \brief Register a translator
148  * \param t populated ast_translator structure
149  * \param module handle to the module that owns this translator
150  * This registers a codec translator with asterisk
151  * \return 0 on success, -1 on failure
152  */
153 int ast_register_translator(struct ast_translator *t, void *module);
154
155 /*!
156  * \brief Unregister a translator
157  * \param t translator to unregister
158  * Unregisters the given tranlator
159  * \return 0 on success, -1 on failure
160  */
161 int ast_unregister_translator(struct ast_translator *t);
162
163 /*!
164  * \brief Chooses the best translation path
165  *
166  * Given a list of sources, and a designed destination format, which should
167  * I choose? Returns 0 on success, -1 if no path could be found.  Modifies
168  * dests and srcs in place 
169  */
170 int ast_translator_best_choice(int *dsts, int *srcs);
171
172 /*! 
173  * \brief Builds a translator path
174  * \param dest destination format
175  * \param source source format
176  * Build a path (possibly NULL) from source to dest 
177  * \return ast_trans_pvt on success, NULL on failure
178  * */
179 struct ast_trans_pvt *ast_translator_build_path(int dest, int source);
180
181 /*!
182  * \brief Frees a translator path
183  * \param tr translator path to get rid of
184  * Frees the given translator path structure
185  */
186 void ast_translator_free_path(struct ast_trans_pvt *tr);
187
188 /*!
189  * \brief translates one or more frames
190  * \param tr translator structure to use for translation
191  * \param f frame to translate
192  * \param consume Whether or not to free the original frame
193  * Apply an input frame into the translator and receive zero or one output frames.  Consume
194  * determines whether the original frame should be freed
195  * \return an ast_frame of the new translation format on success, NULL on failure
196  */
197 struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);
198
199 /*!
200  * \brief Returns the number of steps required to convert from 'src' to 'dest'.
201  * \param dest Destination format
202  * \param src Source format
203  * \return the number of translation steps required, or -1 if no path is available
204  */
205 unsigned int ast_translate_path_steps(unsigned int dest, unsigned int src);
206
207 #if defined(__cplusplus) || defined(c_plusplus)
208 }
209 #endif
210
211 #endif /* _ASTERISK_TRANSLATE_H */