07233e68f64d615243f911d37791a08cee294447
[asterisk/asterisk.git] / include / asterisk / translate.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, 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 Translate via the use of pseudo channels
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 #include "asterisk/frame.h"
33 #include "asterisk/plc.h"
34 #include "asterisk/linkedlists.h"
35
36 /* Declared by individual translators */
37 struct ast_translator_pvt;
38
39 /*! data structure associated with a translator */
40 struct ast_translator {
41         /*! Name of translator */
42         char name[80];
43         /*! Source format */
44         int srcfmt;
45         /*! Destination format */
46         int dstfmt;
47         /*! Private data associated with the translator */
48         struct ast_translator_pvt *(*newpvt)(void);
49         /*! Input frame callback */
50         int (*framein)(struct ast_translator_pvt *pvt, struct ast_frame *in);
51         /*! Output frame callback */
52         struct ast_frame * (*frameout)(struct ast_translator_pvt *pvt);
53         /*! Destroy translator callback */
54         void (*destroy)(struct ast_translator_pvt *pvt);
55         /* For performance measurements */
56         /*! Generate an example frame */
57         struct ast_frame * (*sample)(void);
58         /*! Cost in milliseconds for encoding/decoding 1 second of sound */
59         int cost;
60         /*! For linking, not to be modified by the translator */
61         AST_LIST_ENTRY(ast_translator) list;
62 };
63
64 struct ast_trans_pvt;
65
66 /*! Register a translator */
67 /*! 
68  * \param t populated ast_translator structure
69  * This registers a codec translator with asterisk
70  * Returns 0 on success, -1 on failure
71  */
72 extern int ast_register_translator(struct ast_translator *t);
73
74 /*! Unregister a translator */
75 /*!
76  * \param t translator to unregister
77  * Unregisters the given tranlator
78  * Returns 0 on success, -1 on failure
79  */
80 extern int ast_unregister_translator(struct ast_translator *t);
81
82 /*! Chooses the best translation path */
83 /*! 
84  * Given a list of sources, and a designed destination format, which should
85    I choose? Returns 0 on success, -1 if no path could be found.  Modifies
86    dests and srcs in place 
87    */
88 extern int ast_translator_best_choice(int *dsts, int *srcs);
89
90 /*!Builds a translator path */
91 /*! 
92  * \param dest destination format
93  * \param source source format
94  * Build a path (possibly NULL) from source to dest 
95  * Returns ast_trans_pvt on success, NULL on failure
96  * */
97 extern struct ast_trans_pvt *ast_translator_build_path(int dest, int source);
98
99 /*! Frees a translator path */
100 /*!
101  * \param tr translator path to get rid of
102  * Frees the given translator path structure
103  */
104 extern void ast_translator_free_path(struct ast_trans_pvt *tr);
105
106 /*! translates one or more frames */
107 /*! 
108  * \param tr translator structure to use for translation
109  * \param f frame to translate
110  * \param consume Whether or not to free the original frame
111  * Apply an input frame into the translator and receive zero or one output frames.  Consume
112  * determines whether the original frame should be freed
113  * Returns an ast_frame of the new translation format on success, NULL on failure
114  */
115 extern struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);
116
117 #if defined(__cplusplus) || defined(c_plusplus)
118 }
119 #endif
120
121 #endif /* _ASTERISK_TRANSLATE_H */