118ba6d5564af8037ef712e049ab4f7e31f8508d
[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 /*!
67  * \brief Register a translator
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 /*!
75  * \brief Unregister a translator
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 /*!
83  * \brief Chooses the best translation path
84  *
85  * Given a list of sources, and a designed destination format, which should
86  * I choose? Returns 0 on success, -1 if no path could be found.  Modifies
87  * dests and srcs in place 
88  */
89 extern int ast_translator_best_choice(int *dsts, int *srcs);
90
91 /*! 
92  * \brief Builds a translator path
93  * \param dest destination format
94  * \param source source format
95  * Build a path (possibly NULL) from source to dest 
96  * Returns ast_trans_pvt on success, NULL on failure
97  * */
98 extern struct ast_trans_pvt *ast_translator_build_path(int dest, int source);
99
100 /*!
101  * \brief Frees a translator path
102  * \param tr translator path to get rid of
103  * Frees the given translator path structure
104  */
105 extern void ast_translator_free_path(struct ast_trans_pvt *tr);
106
107 /*!
108  * \brief translates one or more frames
109  * \param tr translator structure to use for translation
110  * \param f frame to translate
111  * \param consume Whether or not to free the original frame
112  * Apply an input frame into the translator and receive zero or one output frames.  Consume
113  * determines whether the original frame should be freed
114  * Returns an ast_frame of the new translation format on success, NULL on failure
115  */
116 extern struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);
117
118 #if defined(__cplusplus) || defined(c_plusplus)
119 }
120 #endif
121
122 #endif /* _ASTERISK_TRANSLATE_H */