Wed Jan 8 2020 09:49:39

Asterisk developer's documentation


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/frame_defs.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 #define AST_JB_IMPL_NAME_SIZE 12
51 
52 /*!
53  * \brief General jitterbuffer configuration.
54  */
56 {
57  /*! \brief Combination of the AST_JB_ENABLED, AST_JB_FORCED and AST_JB_LOG flags. */
58  unsigned int flags;
59  /*! \brief Max size of the jitterbuffer implementation. */
60  long max_size;
61  /*! \brief Resynchronization threshold of the jitterbuffer implementation. */
63  /*! \brief Name of the jitterbuffer implementation to be used. */
65  /*! \brief amount of additional jitterbuffer adjustment */
67 };
68 
69 
70 /* Jitterbuffer configuration property names */
71 #define AST_JB_CONF_PREFIX "jb"
72 #define AST_JB_CONF_ENABLE "enable"
73 #define AST_JB_CONF_FORCE "force"
74 #define AST_JB_CONF_MAX_SIZE "maxsize"
75 #define AST_JB_CONF_RESYNCH_THRESHOLD "resyncthreshold"
76 #define AST_JB_CONF_TARGET_EXTRA "targetextra"
77 #define AST_JB_CONF_IMPL "impl"
78 #define AST_JB_CONF_LOG "log"
79 
80 
81 struct ast_jb_impl;
82 
83 
84 /*!
85  * \brief General jitterbuffer state.
86  */
87 struct ast_jb
88 {
89  /*! \brief Jitterbuffer configuration. */
90  struct ast_jb_conf conf;
91  /*! \brief Jitterbuffer implementation to be used. */
92  const struct ast_jb_impl *impl;
93  /*! \brief Jitterbuffer object, passed to the implementation. */
94  void *jbobj;
95  /*! \brief The time the jitterbuffer was created. */
96  struct timeval timebase;
97  /*! \brief The time the next frame should be played. */
98  long next;
99  /*! \brief Voice format of the last frame in. */
101  /*! \brief File for frame timestamp tracing. */
102  FILE *logfile;
103  /*! \brief Jitterbuffer internal state flags. */
104  unsigned int flags;
105 };
106 
107 
108 /*!
109  * \brief Checks the need of a jb use in a generic bridge.
110  * \param c0 first bridged channel.
111  * \param c1 second bridged channel.
112  *
113  * Called from ast_generic_bridge() when two channels are entering in a bridge.
114  * The function checks the need of a jitterbuffer, depending on both channel's
115  * configuration and technology properties. As a result, this function sets
116  * appropriate internal jb flags to the channels, determining further behaviour
117  * of the bridged jitterbuffers.
118  *
119  * \retval zero if there are no jitter buffers in use
120  * \retval non-zero if there are
121  */
122 int ast_jb_do_usecheck(struct ast_channel *c0, struct ast_channel *c1);
123 
124 
125 /*!
126  * \brief Calculates the time, left to the closest delivery moment in a bridge.
127  * \param c0 first bridged channel.
128  * \param c1 second bridged channel.
129  * \param time_left bridge time limit, or -1 if not set.
130  *
131  * Called from ast_generic_bridge() to determine the maximum time to wait for
132  * activity in ast_waitfor_n() call. If neihter of the channels is using jb,
133  * this function returns the time limit passed.
134  *
135  * \return maximum time to wait.
136  */
137 int ast_jb_get_when_to_wakeup(struct ast_channel *c0, struct ast_channel *c1, int time_left);
138 
139 
140 /*!
141  * \brief Puts a frame into a channel jitterbuffer.
142  * \param chan channel.
143  * \param f frame.
144  *
145  * Called from ast_generic_bridge() to put a frame into a channel's jitterbuffer.
146  * The function will successfuly enqueue a frame if and only if:
147  * 1. the channel is using a jitterbuffer (as determined by ast_jb_do_usecheck()),
148  * 2. the frame's type is AST_FRAME_VOICE,
149  * 3. the frame has timing info set and has length >= 2 ms,
150  * 4. there is no some internal error happened (like failed memory allocation).
151  * Frames, successfuly queued, should be delivered by the channel's jitterbuffer,
152  * when their delivery time has came.
153  * Frames, not successfuly queued, should be delivered immediately.
154  * Dropped by the jb implementation frames are considered successfuly enqueued as
155  * far as they should not be delivered at all.
156  *
157  * \retval 0 if the frame was queued
158  * \retval -1 if not
159  */
160 int ast_jb_put(struct ast_channel *chan, struct ast_frame *f);
161 
162 
163 /*!
164  * \brief Deliver the queued frames that should be delivered now for both channels.
165  * \param c0 first bridged channel.
166  * \param c1 second bridged channel.
167  *
168  * Called from ast_generic_bridge() to deliver any frames, that should be delivered
169  * for the moment of invocation. Does nothing if neihter of the channels is using jb
170  * or has any frames currently queued in. The function delivers frames usig ast_write()
171  * each of the channels.
172  */
173 void ast_jb_get_and_deliver(struct ast_channel *c0, struct ast_channel *c1);
174 
175 
176 /*!
177  * \brief Destroys jitterbuffer on a channel.
178  * \param chan channel.
179  *
180  * Called from ast_channel_free() when a channel is destroyed.
181  */
182 void ast_jb_destroy(struct ast_channel *chan);
183 
184 
185 /*!
186  * \brief Sets jitterbuffer configuration property.
187  * \param conf configuration to store the property in.
188  * \param varname property name.
189  * \param value property value.
190  *
191  * Called from a channel driver to build a jitterbuffer configuration typically when
192  * reading a configuration file. It is not necessary for a channel driver to know
193  * each of the jb configuration property names. The jitterbuffer itself knows them.
194  * The channel driver can pass each config var it reads through this function. It will
195  * return 0 if the variable was consumed from the jb conf.
196  *
197  * \return zero if the property was set to the configuration, -1 if not.
198  */
199 int ast_jb_read_conf(struct ast_jb_conf *conf, const char *varname, const char *value);
200 
201 
202 /*!
203  * \brief Configures a jitterbuffer on a channel.
204  * \param chan channel to configure.
205  * \param conf configuration to apply.
206  *
207  * Called from a channel driver when a channel is created and its jitterbuffer needs
208  * to be configured.
209  */
210 void ast_jb_configure(struct ast_channel *chan, const struct ast_jb_conf *conf);
211 
212 
213 /*!
214  * \brief Copies a channel's jitterbuffer configuration.
215  * \param chan channel.
216  * \param conf destination.
217  */
218 void ast_jb_get_config(const struct ast_channel *chan, struct ast_jb_conf *conf);
219 
220 /*!
221  * \brief drops all frames from a jitterbuffer and resets it
222  * \param c0 one channel of a bridge
223  * \param c1 the other channel of the bridge
224  */
225 void ast_jb_empty_and_reset(struct ast_channel *c0, struct ast_channel *c1);
226 
227 #if defined(__cplusplus) || defined(c_plusplus)
228 }
229 #endif
230 
231 #endif /* _ABSTRACT_JB_H_ */
Main Channel structure associated with a channel.
Definition: channel.h:742
int ast_jb_put(struct ast_channel *chan, struct ast_frame *f)
Puts a frame into a channel jitterbuffer.
Definition: abstract_jb.c:306
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:627
int ast_jb_read_conf(struct ast_jb_conf *conf, const char *varname, const char *value)
Sets jitterbuffer configuration property.
Definition: abstract_jb.c:577
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:266
struct ast_jb_conf conf
Jitterbuffer configuration.
Definition: abstract_jb.h:90
#define AST_JB_IMPL_NAME_SIZE
Definition: abstract_jb.h:50
int value
Definition: syslog.c:39
unsigned int flags
Jitterbuffer internal state flags.
Definition: abstract_jb.h:104
long resync_threshold
Resynchronization threshold of the jitterbuffer implementation.
Definition: abstract_jb.h:62
void ast_jb_destroy(struct ast_channel *chan)
Destroys jitterbuffer on a channel.
Definition: abstract_jb.c:536
void * jbobj
Jitterbuffer object, passed to the implementation.
Definition: abstract_jb.h:94
long target_extra
amount of additional jitterbuffer adjustment
Definition: abstract_jb.h:66
char impl[AST_JB_IMPL_NAME_SIZE]
Name of the jitterbuffer implementation to be used.
Definition: abstract_jb.h:64
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:622
int64_t format_t
Definition: frame_defs.h:32
struct ast_jb_impl * impl
Jitterbuffer implementation to be used.
Definition: abstract_jb.h:92
General jitterbuffer state.
Definition: abstract_jb.h:87
FILE * logfile
File for frame timestamp tracing.
Definition: abstract_jb.h:102
static struct ast_format f[]
Definition: format_g726.c:181
format_t last_format
Voice format of the last frame in.
Definition: abstract_jb.h:100
unsigned int flags
Combination of the AST_JB_ENABLED, AST_JB_FORCED and AST_JB_LOG flags.
Definition: abstract_jb.h:58
void ast_jb_configure(struct ast_channel *chan, const struct ast_jb_conf *conf)
Configures a jitterbuffer on a channel.
Definition: abstract_jb.c:616
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:371
Data structure associated with a single frame of data.
Definition: frame.h:142
struct timeval timebase
The time the jitterbuffer was created.
Definition: abstract_jb.h:96
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:205
Asterisk internal frame definitions.
long max_size
Max size of the jitterbuffer implementation.
Definition: abstract_jb.h:60
Jitterbuffer implementation private struct.
Definition: abstract_jb.c:80
General jitterbuffer configuration.
Definition: abstract_jb.h:55
long next
The time the next frame should be played.
Definition: abstract_jb.h:98