d884ce3d54badf9da62f5ee1dbaea67159f72ccf
[asterisk/asterisk.git] / include / asterisk / abstract_jb.h
1 /*
2  * abstract_jb: common implementation-independent jitterbuffer stuff
3  *
4  * Copyright (C) 2005, Attractel OOD
5  *
6  * Contributors:
7  * Slav Klenov <slav@securax.org>
8  *
9  * See http://www.asterisk.org for more information about
10  * the Asterisk project. Please do not directly contact
11  * any of the maintainers of this project for assistance;
12  * the project provides a web site, mailing lists and IRC
13  * channels for your use.
14  *
15  * This program is free software, distributed under the terms of
16  * the GNU General Public License Version 2. See the LICENSE file
17  * at the top of the source tree.
18  *
19  * A license has been granted to Digium (via disclaimer) for the use of
20  * this code.
21  */
22
23 /*! \file
24  *
25  * \brief Common implementation-independent jitterbuffer stuff.
26  * 
27  * \author Slav Klenov <slav@securax.org>
28  */
29
30 #ifndef _ABSTRACT_JB_H_
31 #define _ABSTRACT_JB_H_
32
33 #include <sys/time.h>
34
35 #if defined(__cplusplus) || defined(c_plusplus)
36 extern "C" {
37 #endif
38
39 struct ast_frame;
40
41 /* Configuration flags */
42 enum {
43         AST_JB_ENABLED = (1 << 0),
44         AST_JB_FORCED =  (1 << 1),
45         AST_JB_LOG =     (1 << 2)
46 };
47
48 #define AST_JB_IMPL_NAME_SIZE 12
49
50 /*!
51  * \brief General jitterbuffer configuration.
52  */
53 struct ast_jb_conf
54 {
55         /*! \brief Combination of the AST_JB_ENABLED, AST_JB_FORCED and AST_JB_LOG flags. */
56         unsigned int flags;
57         /*! \brief Max size of the jitterbuffer implementation. */
58         long max_size;
59         /*! \brief Resynchronization threshold of the jitterbuffer implementation. */
60         long resync_threshold;
61         /*! \brief Name of the jitterbuffer implementation to be used. */
62         char impl[AST_JB_IMPL_NAME_SIZE];
63 };
64
65
66 /* Jitterbuffer configuration property names */
67 #define AST_JB_CONF_PREFIX "jb"
68 #define AST_JB_CONF_ENABLE "enable"
69 #define AST_JB_CONF_FORCE "force"
70 #define AST_JB_CONF_MAX_SIZE "maxsize"
71 #define AST_JB_CONF_RESYNCH_THRESHOLD "resyncthreshold"
72 #define AST_JB_CONF_IMPL "impl"
73 #define AST_JB_CONF_LOG "log"
74
75
76 struct ast_jb_impl;
77
78
79 /*!
80  * \brief General jitterbuffer state.
81  */
82 struct ast_jb
83 {
84         /*! \brief Jitterbuffer configuration. */
85         struct ast_jb_conf conf;
86         /*! \brief Jitterbuffer implementation to be used. */
87         struct ast_jb_impl *impl;
88         /*! \brief Jitterbuffer object, passed to the implementation. */
89         void *jbobj;
90         /*! \brief The time the jitterbuffer was created. */
91         struct timeval timebase;
92         /*! \brief The time the next frame should be played. */
93         long next;
94         /*! \brief Voice format of the last frame in. */
95         int last_format;
96         /*! \brief File for frame timestamp tracing. */
97         FILE *logfile;
98         /*! \brief Jitterbuffer internal state flags. */
99         unsigned int flags;
100 };
101
102
103 /*!
104  * \brief Checks the need of a jb use in a generic bridge.
105  * \param c0 first bridged channel.
106  * \param c1 second bridged channel.
107  *
108  * Called from ast_generic_bridge() when two channels are entering in a bridge.
109  * The function checks the need of a jitterbuffer, depending on both channel's
110  * configuration and technology properties. As a result, this function sets
111  * appropriate internal jb flags to the channels, determining further behaviour
112  * of the bridged jitterbuffers.
113  *
114  * \retval zero if there are no jitter buffers in use
115  * \retval non-zero if there are
116  */
117 int ast_jb_do_usecheck(struct ast_channel *c0, struct ast_channel *c1);
118
119
120 /*!
121  * \brief Calculates the time, left to the closest delivery moment in a bridge.
122  * \param c0 first bridged channel.
123  * \param c1 second bridged channel.
124  * \param time_left bridge time limit, or -1 if not set.
125  *
126  * Called from ast_generic_bridge() to determine the maximum time to wait for
127  * activity in ast_waitfor_n() call. If neihter of the channels is using jb,
128  * this function returns the time limit passed.
129  *
130  * \return maximum time to wait.
131  */
132 int ast_jb_get_when_to_wakeup(struct ast_channel *c0, struct ast_channel *c1, int time_left);
133
134
135 /*!
136  * \brief Puts a frame into a channel jitterbuffer.
137  * \param chan channel.
138  * \param f frame.
139  *
140  * Called from ast_generic_bridge() to put a frame into a channel's jitterbuffer.
141  * The function will successfuly enqueue a frame if and only if:
142  * 1. the channel is using a jitterbuffer (as determined by ast_jb_do_usecheck()),
143  * 2. the frame's type is AST_FRAME_VOICE,
144  * 3. the frame has timing info set and has length >= 2 ms,
145  * 4. there is no some internal error happened (like failed memory allocation).
146  * Frames, successfuly queued, should be delivered by the channel's jitterbuffer,
147  * when their delivery time has came.
148  * Frames, not successfuly queued, should be delivered immediately.
149  * Dropped by the jb implementation frames are considered successfuly enqueued as
150  * far as they should not be delivered at all.
151  *
152  * \retval 0 if the frame was queued
153  * \retval -1 if not
154  */
155 int ast_jb_put(struct ast_channel *chan, struct ast_frame *f);
156
157
158 /*!
159  * \brief Deliver the queued frames that should be delivered now for both channels.
160  * \param c0 first bridged channel.
161  * \param c1 second bridged channel.
162  *
163  * Called from ast_generic_bridge() to deliver any frames, that should be delivered
164  * for the moment of invocation. Does nothing if neihter of the channels is using jb
165  * or has any frames currently queued in. The function delivers frames usig ast_write()
166  * each of the channels.
167  */
168 void ast_jb_get_and_deliver(struct ast_channel *c0, struct ast_channel *c1);
169
170
171 /*!
172  * \brief Destroys jitterbuffer on a channel.
173  * \param chan channel.
174  *
175  * Called from ast_channel_free() when a channel is destroyed.
176  */
177 void ast_jb_destroy(struct ast_channel *chan);
178
179
180 /*!
181  * \brief Sets jitterbuffer configuration property.
182  * \param conf configuration to store the property in.
183  * \param varname property name.
184  * \param value property value.
185  *
186  * Called from a channel driver to build a jitterbuffer configuration tipically when
187  * reading a configuration file. It is not neccessary for a channel driver to know
188  * each of the jb configuration property names. The jitterbuffer itself knows them.
189  * The channel driver can pass each config var it reads through this function. It will
190  * return 0 if the variable was consumed from the jb conf.
191  *
192  * \return zero if the property was set to the configuration, -1 if not.
193  */
194 int ast_jb_read_conf(struct ast_jb_conf *conf, const char *varname, const char *value);
195
196
197 /*!
198  * \brief Configures a jitterbuffer on a channel.
199  * \param chan channel to configure.
200  * \param conf configuration to apply.
201  *
202  * Called from a channel driver when a channel is created and its jitterbuffer needs
203  * to be configured.
204  */
205 void ast_jb_configure(struct ast_channel *chan, const struct ast_jb_conf *conf);
206
207
208 /*!
209  * \brief Copies a channel's jitterbuffer configuration.
210  * \param chan channel.
211  * \param conf destination.
212  */
213 void ast_jb_get_config(const struct ast_channel *chan, struct ast_jb_conf *conf);
214
215 /*!
216  * \brief drops all frames from a jitterbuffer and resets it
217  * \param c0 one channel of a bridge
218  * \param c1 the other channel of the bridge
219  */
220 void ast_jb_empty_and_reset(struct ast_channel *c0, struct ast_channel *c1);
221
222 #if defined(__cplusplus) || defined(c_plusplus)
223 }
224 #endif
225
226 #endif /* _ABSTRACT_JB_H_ */