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