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