Wed Jan 8 2020 09:49:51

Asterisk developer's documentation


translate.h
Go to the documentation of this file.
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  */
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 native_plc; /*!< true if the translator can do native plc */
109 
110  struct ast_module *module; /*!< opaque reference to the parent module */
111 
112  int cost; /*!< Cost in milliseconds for encoding/decoding 1 second of sound */
113  int active; /*!< Whether this translator should be used or not */
114  AST_LIST_ENTRY(ast_translator) list; /*!< link field */
115 };
116 
117 /*! \brief
118  * Default structure for translators, with the basic fields and buffers,
119  * all allocated as part of the same chunk of memory. The buffer is
120  * preceded by \ref AST_FRIENDLY_OFFSET bytes in front of the user portion.
121  * 'buf' points right after this space.
122  *
123  * *_framein() routines operate in two ways:
124  * 1. some convert on the fly and place the data directly in outbuf;
125  * in this case 'samples' and 'datalen' contain the number of samples
126  * and number of bytes available in the buffer.
127  * In this case we can use a generic *_frameout() routine that simply
128  * takes whatever is there and places it into the output frame.
129  * 2. others simply store the (unconverted) samples into a working
130  * buffer, and leave the conversion task to *_frameout().
131  * In this case, the intermediate buffer must be in the private
132  * descriptor, 'datalen' is left to 0, while 'samples' is still
133  * updated with the number of samples received.
134  */
136  struct ast_translator *t;
137  struct ast_frame f; /*!< used in frameout */
138  int samples; /*!< samples available in outbuf */
139  /*! \brief actual space used in outbuf */
140  int datalen;
141  void *pvt; /*!< more private data, if any */
142  union {
143  char *c; /*!< the useful portion of the buffer */
144  unsigned char *uc; /*!< the useful portion of the buffer */
145  int16_t *i16;
146  uint8_t *ui8;
147  } outbuf;
148  plc_state_t *plc; /*!< optional plc pointer */
149  struct ast_trans_pvt *next; /*!< next in translator chain */
150  struct timeval nextin;
151  struct timeval nextout;
152 };
153 
154 /*! \brief generic frameout function */
155 struct ast_frame *ast_trans_frameout(struct ast_trans_pvt *pvt,
156  int datalen, int samples);
157 
158 struct ast_trans_pvt;
159 
160 /*!
161  * \brief Register a translator
162  * This registers a codec translator with asterisk
163  * \param t populated ast_translator structure
164  * \param module handle to the module that owns this translator
165  * \return 0 on success, -1 on failure
166  */
168 
169 /*! \brief See \ref __ast_register_translator() */
170 #define ast_register_translator(t) __ast_register_translator(t, ast_module_info->self)
171 
172 /*!
173  * \brief Unregister a translator
174  * Unregisters the given tranlator
175  * \param t translator to unregister
176  * \return 0 on success, -1 on failure
177  */
179 
180 /*!
181  * \brief Activate a previously deactivated translator
182  * \param t translator to activate
183  * \return nothing
184  *
185  * Enables the specified translator for use.
186  */
188 
189 /*!
190  * \brief Deactivate a translator
191  * \param t translator to deactivate
192  * \return nothing
193  *
194  * Disables the specified translator from being used.
195  */
197 
198 /*!
199  * \brief Chooses the best translation path
200  *
201  * Given a list of sources, and a designed destination format, which should
202  * I choose?
203  * \return Returns 0 on success, -1 if no path could be found.
204  * \note Modifies dests and srcs in place
205  */
207 
208 /*!
209  * \brief Builds a translator path
210  * Build a path (possibly NULL) from source to dest
211  * \param dest destination format
212  * \param source source format
213  * \return ast_trans_pvt on success, NULL on failure
214  * */
216 
217 /*!
218  * \brief Frees a translator path
219  * Frees the given translator path structure
220  * \param tr translator path to get rid of
221  */
222 void ast_translator_free_path(struct ast_trans_pvt *tr);
223 
224 /*!
225  * \brief translates one or more frames
226  * Apply an input frame into the translator and receive zero or one output frames. Consume
227  * determines whether the original frame should be freed
228  * \param tr translator structure to use for translation
229  * \param f frame to translate
230  * \param consume Whether or not to free the original frame
231  * \return an ast_frame of the new translation format on success, NULL on failure
232  */
233 struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);
234 
235 /*!
236  * \brief Returns the number of steps required to convert from 'src' to 'dest'.
237  * \param dest destination format
238  * \param src source format
239  * \return the number of translation steps required, or -1 if no path is available
240  */
241 unsigned int ast_translate_path_steps(format_t dest, format_t src);
242 
243 /*!
244  * \brief Mask off unavailable formats from a format bitmask
245  * \param dest possible destination formats
246  * \param src source formats
247  * \return the destination formats that are available in the source or translatable
248  *
249  * The result will include all formats from 'dest' that are either present
250  * in 'src' or translatable from a format present in 'src'.
251  *
252  * \note Only a single audio format and a single video format can be
253  * present in 'src', or the function will produce unexpected results.
254  */
256 
257 /*!
258  * \brief Puts a string representation of the translation path into outbuf
259  * \param translator structure containing the translation path
260  * \param ast_str output buffer
261  * \retval on success pointer to beginning of outbuf. on failure "".
262  */
263 const char *ast_translate_path_to_str(struct ast_trans_pvt *t, struct ast_str **str);
264 
265 #if defined(__cplusplus) || defined(c_plusplus)
266 }
267 #endif
268 
269 #endif /* _ASTERISK_TRANSLATE_H */
struct ast_frame * ast_trans_frameout(struct ast_trans_pvt *pvt, int datalen, int samples)
generic frameout function
Definition: translate.c:235
int datalen
actual space used in outbuf
Definition: translate.h:140
Descriptor of a translator.
Definition: translate.h:71
void ast_translator_activate(struct ast_translator *t)
Activate a previously deactivated translator.
Definition: translate.c:967
unsigned char * uc
Definition: translate.h:144
const char name[80]
Definition: translate.h:72
plc_state_t * plc
Definition: translate.h:148
struct ast_frame * ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume)
translates one or more frames Apply an input frame into the translator and receive zero or one output...
Definition: translate.c:328
struct ast_trans_pvt * next
Definition: translate.h:149
const char * str
Definition: app_jack.c:144
void * pvt
Definition: translate.h:141
int16_t * i16
Definition: translate.h:145
int __ast_register_translator(struct ast_translator *t, struct ast_module *module)
Register a translator This registers a codec translator with asterisk.
Definition: translate.c:853
struct ast_trans_pvt * ast_translator_build_path(format_t dest, format_t source)
Builds a translator path Build a path (possibly NULL) from source to dest.
Definition: translate.c:282
struct ast_module * module
Definition: translate.h:110
const char * src
Definition: frame.h:158
Asterisk internal frame definitions.
int datalen
Definition: frame.h:148
int ast_unregister_translator(struct ast_translator *t)
Unregister a translator Unregisters the given tranlator.
Definition: translate.c:942
A set of macros to manage forward-linked lists.
uint8_t * ui8
Definition: translate.h:146
int buf_size
size of outbuf, in bytes. Mandatory. The wrapper code will also allocate an AST_FRIENDLY_OFFSET space...
Definition: translate.h:105
format_t ast_translate_available_formats(format_t dest, format_t src)
Mask off unavailable formats from a format bitmask.
Definition: translate.c:1081
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:364
Default structure for translators, with the basic fields and buffers, all allocated as part of the sa...
Definition: translate.h:135
int(* newpvt)(struct ast_trans_pvt *)
Definition: translate.h:78
int64_t format_t
Definition: frame_defs.h:32
unsigned int ast_translate_path_steps(format_t dest, format_t src)
Returns the number of steps required to convert from &#39;src&#39; to &#39;dest&#39;.
Definition: translate.c:1059
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
void ast_translator_deactivate(struct ast_translator *t)
Deactivate a translator.
Definition: translate.c:975
format_t dstfmt
Definition: translate.h:75
static struct ast_format f[]
Definition: format_g726.c:181
const char * ast_translate_path_to_str(struct ast_trans_pvt *t, struct ast_str **str)
Puts a string representation of the translation path into outbuf.
Definition: translate.c:630
int(* framein)(struct ast_trans_pvt *pvt, struct ast_frame *in)
Definition: translate.h:81
SpanDSP - a series of DSP components for telephony.
Data structure associated with a single frame of data.
Definition: frame.h:142
format_t srcfmt
Definition: translate.h:73
struct ast_translator * t
Definition: translate.h:136
struct ast_translator::@212 list
format_t ast_translator_best_choice(format_t *dsts, format_t *srcs)
Chooses the best translation path.
Definition: translate.c:984
void ast_translator_free_path(struct ast_trans_pvt *tr)
Frees a translator path Frees the given translator path structure.
Definition: translate.c:272
int samples
Definition: frame.h:150
void(* destroy)(struct ast_trans_pvt *pvt)
Definition: translate.h:89
int buffer_samples
size of outbuf, in samples. Leave it 0 if you want the framein callback deal with the frame...
Definition: translate.h:100