CLI: Create ast_cli_completion_vector.
[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 #include "asterisk/format.h"
36
37 #if defined(__cplusplus) || defined(c_plusplus)
38 extern "C" {
39 #endif
40
41 struct ast_frame;
42
43 /* Configuration flags */
44 enum {
45         AST_JB_ENABLED = (1 << 0),
46         AST_JB_FORCED =  (1 << 1),
47         AST_JB_LOG =     (1 << 2)
48 };
49
50 enum ast_jb_type {
51         AST_JB_FIXED,
52         AST_JB_ADAPTIVE,
53 };
54
55 /*! Abstract return codes */
56 enum {
57         AST_JB_IMPL_OK,
58         AST_JB_IMPL_DROP,
59         AST_JB_IMPL_INTERP,
60         AST_JB_IMPL_NOFRAME
61 };
62
63 #define AST_JB_IMPL_NAME_SIZE 12
64
65 /*!
66  * \brief General jitterbuffer configuration.
67  */
68 struct ast_jb_conf
69 {
70         /*! \brief Combination of the AST_JB_ENABLED, AST_JB_FORCED and AST_JB_LOG flags. */
71         unsigned int flags;
72         /*! \brief Max size of the jitterbuffer implementation. */
73         long max_size;
74         /*! \brief Resynchronization threshold of the jitterbuffer implementation. */
75         long resync_threshold;
76         /*! \brief Name of the jitterbuffer implementation to be used. */
77         char impl[AST_JB_IMPL_NAME_SIZE];
78         /*! \brief amount of additional jitterbuffer adjustment */
79         long target_extra;
80 };
81
82
83 /* Jitterbuffer configuration property names */
84 #define AST_JB_CONF_PREFIX "jb"
85 #define AST_JB_CONF_ENABLE "enable"
86 #define AST_JB_CONF_FORCE "force"
87 #define AST_JB_CONF_MAX_SIZE "maxsize"
88 #define AST_JB_CONF_RESYNCH_THRESHOLD "resyncthreshold"
89 #define AST_JB_CONF_TARGET_EXTRA "targetextra"
90 #define AST_JB_CONF_IMPL "impl"
91 #define AST_JB_CONF_LOG "log"
92
93 /* Hooks for the abstract jb implementation */
94 /*! \brief Create */
95 typedef void * (*jb_create_impl)(struct ast_jb_conf *general_config);
96 /*! \brief Destroy */
97 typedef void (*jb_destroy_impl)(void *jb);
98 /*! \brief Put first frame */
99 typedef int (*jb_put_first_impl)(void *jb, struct ast_frame *fin, long now);
100 /*! \brief Put frame */
101 typedef int (*jb_put_impl)(void *jb, struct ast_frame *fin, long now);
102 /*! \brief Get frame for now */
103 typedef int (*jb_get_impl)(void *jb, struct ast_frame **fout, long now, long interpl);
104 /*! \brief Get next */
105 typedef long (*jb_next_impl)(void *jb);
106 /*! \brief Remove first frame */
107 typedef int (*jb_remove_impl)(void *jb, struct ast_frame **fout);
108 /*! \brief Force resynch */
109 typedef void (*jb_force_resynch_impl)(void *jb);
110 /*! \brief Empty and reset jb */
111 typedef void (*jb_empty_and_reset_impl)(void *jb);
112 /*! \brief Check if late */
113 typedef int (*jb_is_late_impl)(void *jb, long ts);
114
115
116 /*!
117  * \brief Jitterbuffer implementation struct.
118  */
119 struct ast_jb_impl
120 {
121         char name[AST_JB_IMPL_NAME_SIZE];
122         enum ast_jb_type type;
123         jb_create_impl create;
124         jb_destroy_impl destroy;
125         jb_put_first_impl put_first;
126         jb_put_impl put;
127         jb_get_impl get;
128         jb_next_impl next;
129         jb_remove_impl remove;
130         jb_force_resynch_impl force_resync;
131         jb_empty_and_reset_impl empty_and_reset;
132         jb_is_late_impl is_late;
133 };
134
135 /*!
136  * \brief General jitterbuffer state.
137  */
138 struct ast_jb
139 {
140         /*! \brief Jitterbuffer configuration. */
141         struct ast_jb_conf conf;
142         /*! \brief Jitterbuffer implementation to be used. */
143         const struct ast_jb_impl *impl;
144         /*! \brief Jitterbuffer object, passed to the implementation. */
145         void *jbobj;
146         /*! \brief The time the jitterbuffer was created. */
147         struct timeval timebase;
148         /*! \brief The time the next frame should be played. */
149         long next;
150         /*! \brief Voice format of the last frame in. */
151         struct ast_format *last_format;
152         /*! \brief File for frame timestamp tracing. */
153         FILE *logfile;
154         /*! \brief Jitterbuffer internal state flags. */
155         unsigned int flags;
156 };
157
158
159 /*!
160  * \brief Checks the need of a jb use in a generic bridge.
161  * \param c0 first bridged channel.
162  * \param c1 second bridged channel.
163  *
164  * Called from ast_generic_bridge() when two channels are entering in a bridge.
165  * The function checks the need of a jitterbuffer, depending on both channel's
166  * configuration and technology properties. As a result, this function sets
167  * appropriate internal jb flags to the channels, determining further behaviour
168  * of the bridged jitterbuffers.
169  *
170  * \retval zero if there are no jitter buffers in use
171  * \retval non-zero if there are
172  */
173 int ast_jb_do_usecheck(struct ast_channel *c0, struct ast_channel *c1);
174
175
176 /*!
177  * \brief Calculates the time, left to the closest delivery moment in a bridge.
178  * \param c0 first bridged channel.
179  * \param c1 second bridged channel.
180  * \param time_left bridge time limit, or -1 if not set.
181  *
182  * Called from ast_generic_bridge() to determine the maximum time to wait for
183  * activity in ast_waitfor_n() call. If neihter of the channels is using jb,
184  * this function returns the time limit passed.
185  *
186  * \return maximum time to wait.
187  */
188 int ast_jb_get_when_to_wakeup(struct ast_channel *c0, struct ast_channel *c1, int time_left);
189
190
191 /*!
192  * \brief Puts a frame into a channel jitterbuffer.
193  * \param chan channel.
194  * \param f frame.
195  *
196  * Called from ast_generic_bridge() to put a frame into a channel's jitterbuffer.
197  * The function will successfuly enqueue a frame if and only if:
198  * 1. the channel is using a jitterbuffer (as determined by ast_jb_do_usecheck()),
199  * 2. the frame's type is AST_FRAME_VOICE,
200  * 3. the frame has timing info set and has length >= 2 ms,
201  * 4. there is no some internal error happened (like failed memory allocation).
202  * Frames, successfuly queued, should be delivered by the channel's jitterbuffer,
203  * when their delivery time has came.
204  * Frames, not successfuly queued, should be delivered immediately.
205  * Dropped by the jb implementation frames are considered successfuly enqueued as
206  * far as they should not be delivered at all.
207  *
208  * \retval 0 if the frame was queued
209  * \retval -1 if not
210  */
211 int ast_jb_put(struct ast_channel *chan, struct ast_frame *f);
212
213
214 /*!
215  * \brief Deliver the queued frames that should be delivered now for both channels.
216  * \param c0 first bridged channel.
217  * \param c1 second bridged channel.
218  *
219  * Called from ast_generic_bridge() to deliver any frames, that should be delivered
220  * for the moment of invocation. Does nothing if neihter of the channels is using jb
221  * or has any frames currently queued in. The function delivers frames usig ast_write()
222  * each of the channels.
223  */
224 void ast_jb_get_and_deliver(struct ast_channel *c0, struct ast_channel *c1);
225
226
227 /*!
228  * \brief Destroys jitterbuffer on a channel.
229  * \param chan channel.
230  *
231  * Called from ast_channel_free() when a channel is destroyed.
232  */
233 void ast_jb_destroy(struct ast_channel *chan);
234
235
236 /*!
237  * \brief Sets jitterbuffer configuration property.
238  * \param conf configuration to store the property in.
239  * \param varname property name.
240  * \param value property value.
241  *
242  * Called from a channel driver to build a jitterbuffer configuration typically when
243  * reading a configuration file. It is not necessary for a channel driver to know
244  * each of the jb configuration property names. The jitterbuffer itself knows them.
245  * The channel driver can pass each config var it reads through this function. It will
246  * return 0 if the variable was consumed from the jb conf.
247  *
248  * \return zero if the property was set to the configuration, -1 if not.
249  */
250 int ast_jb_read_conf(struct ast_jb_conf *conf, const char *varname, const char *value);
251
252 /*!
253  * \since 12.0
254  * \brief Sets a jitterbuffer frame hook on the channel based on the channel's stored
255  *        jitterbuffer configuration
256  *
257  * \param chan Which channel is being set up
258  */
259 void ast_jb_enable_for_channel(struct ast_channel *chan);
260
261 /*!
262  * \brief Configures a jitterbuffer on a channel.
263  * \param chan channel to configure.
264  * \param conf configuration to apply.
265  *
266  * Called from a channel driver when a channel is created and its jitterbuffer needs
267  * to be configured.
268  */
269 void ast_jb_configure(struct ast_channel *chan, const struct ast_jb_conf *conf);
270
271 /*!
272  * \brief Copies a channel's jitterbuffer configuration.
273  * \param chan channel.
274  * \param conf destination.
275  */
276 void ast_jb_get_config(const struct ast_channel *chan, struct ast_jb_conf *conf);
277
278 /*!
279  * \brief drops all frames from a jitterbuffer and resets it
280  * \param c0 one channel of a bridge
281  * \param c1 the other channel of the bridge
282  */
283 void ast_jb_empty_and_reset(struct ast_channel *c0, struct ast_channel *c1);
284
285 const struct ast_jb_impl *ast_jb_get_impl(enum ast_jb_type type);
286
287 /*!
288  * \since 12
289  * \brief Sets the contents of an ast_jb_conf struct to the default jitterbuffer settings
290  *
291  * \param conf Which jitterbuffer is being set
292  */
293 void ast_jb_conf_default(struct ast_jb_conf *conf);
294
295 /*!
296  * \since 12
297  * \brief Applies a jitterbuffer framehook to a channel based on a provided jitterbuffer config
298  *
299  * \param chan Which channel the jitterbuffer is being set on
300  * \param jb_conf Configuration to use for the jitterbuffer
301  * \param prefer_existing If this is true and a jitterbuffer already exists for the channel,
302  *        use the existing jitterbuffer
303  */
304 void ast_jb_create_framehook(struct ast_channel *chan, struct ast_jb_conf *jb_conf, int prefer_existing);
305
306 #if defined(__cplusplus) || defined(c_plusplus)
307 }
308 #endif
309
310 #endif /* _ABSTRACT_JB_H_ */