abstract_jb.h

Go to the documentation of this file.
00001 /*
00002  * abstract_jb: common implementation-independent jitterbuffer stuff
00003  *
00004  * Copyright (C) 2005, Attractel OOD
00005  *
00006  * Contributors:
00007  * Slav Klenov <slav@securax.org>
00008  *
00009  * See http://www.asterisk.org for more information about
00010  * the Asterisk project. Please do not directly contact
00011  * any of the maintainers of this project for assistance;
00012  * the project provides a web site, mailing lists and IRC
00013  * channels for your use.
00014  *
00015  * This program is free software, distributed under the terms of
00016  * the GNU General Public License Version 2. See the LICENSE file
00017  * at the top of the source tree.
00018  *
00019  * A license has been granted to Digium (via disclaimer) for the use of
00020  * this code.
00021  */
00022 
00023 /*! \file
00024  *
00025  * \brief Common implementation-independent jitterbuffer stuff.
00026  * 
00027  * \author Slav Klenov <slav@securax.org>
00028  */
00029 
00030 #ifndef _ABSTRACT_JB_H_
00031 #define _ABSTRACT_JB_H_
00032 
00033 #include <sys/time.h>
00034 
00035 #include "asterisk/format.h"
00036 
00037 #if defined(__cplusplus) || defined(c_plusplus)
00038 extern "C" {
00039 #endif
00040 
00041 struct ast_frame;
00042 
00043 /* Configuration flags */
00044 enum {
00045    AST_JB_ENABLED = (1 << 0),
00046    AST_JB_FORCED =  (1 << 1),
00047    AST_JB_LOG =     (1 << 2)
00048 };
00049 
00050 enum ast_jb_type {
00051    AST_JB_FIXED,
00052    AST_JB_ADAPTIVE,
00053 };
00054 
00055 /*! Abstract return codes */
00056 enum {
00057    AST_JB_IMPL_OK,
00058    AST_JB_IMPL_DROP,
00059    AST_JB_IMPL_INTERP,
00060    AST_JB_IMPL_NOFRAME
00061 };
00062 
00063 #define AST_JB_IMPL_NAME_SIZE 12
00064 
00065 /*!
00066  * \brief General jitterbuffer configuration.
00067  */
00068 struct ast_jb_conf
00069 {
00070    /*! \brief Combination of the AST_JB_ENABLED, AST_JB_FORCED and AST_JB_LOG flags. */
00071    unsigned int flags;
00072    /*! \brief Max size of the jitterbuffer implementation. */
00073    long max_size;
00074    /*! \brief Resynchronization threshold of the jitterbuffer implementation. */
00075    long resync_threshold;
00076    /*! \brief Name of the jitterbuffer implementation to be used. */
00077    char impl[AST_JB_IMPL_NAME_SIZE];
00078    /*! \brief amount of additional jitterbuffer adjustment */
00079    long target_extra;
00080 };
00081 
00082 
00083 /* Jitterbuffer configuration property names */
00084 #define AST_JB_CONF_PREFIX "jb"
00085 #define AST_JB_CONF_ENABLE "enable"
00086 #define AST_JB_CONF_FORCE "force"
00087 #define AST_JB_CONF_MAX_SIZE "maxsize"
00088 #define AST_JB_CONF_RESYNCH_THRESHOLD "resyncthreshold"
00089 #define AST_JB_CONF_TARGET_EXTRA "targetextra"
00090 #define AST_JB_CONF_IMPL "impl"
00091 #define AST_JB_CONF_LOG "log"
00092 
00093 /* Hooks for the abstract jb implementation */
00094 /*! \brief Create */
00095 typedef void * (*jb_create_impl)(struct ast_jb_conf *general_config);
00096 /*! \brief Destroy */
00097 typedef void (*jb_destroy_impl)(void *jb);
00098 /*! \brief Put first frame */
00099 typedef int (*jb_put_first_impl)(void *jb, struct ast_frame *fin, long now);
00100 /*! \brief Put frame */
00101 typedef int (*jb_put_impl)(void *jb, struct ast_frame *fin, long now);
00102 /*! \brief Get frame for now */
00103 typedef int (*jb_get_impl)(void *jb, struct ast_frame **fout, long now, long interpl);
00104 /*! \brief Get next */
00105 typedef long (*jb_next_impl)(void *jb);
00106 /*! \brief Remove first frame */
00107 typedef int (*jb_remove_impl)(void *jb, struct ast_frame **fout);
00108 /*! \brief Force resynch */
00109 typedef void (*jb_force_resynch_impl)(void *jb);
00110 /*! \brief Empty and reset jb */
00111 typedef void (*jb_empty_and_reset_impl)(void *jb);
00112 
00113 
00114 /*!
00115  * \brief Jitterbuffer implementation struct.
00116  */
00117 struct ast_jb_impl
00118 {
00119    char name[AST_JB_IMPL_NAME_SIZE];
00120    enum ast_jb_type type;
00121    jb_create_impl create;
00122    jb_destroy_impl destroy;
00123    jb_put_first_impl put_first;
00124    jb_put_impl put;
00125    jb_get_impl get;
00126    jb_next_impl next;
00127    jb_remove_impl remove;
00128    jb_force_resynch_impl force_resync;
00129    jb_empty_and_reset_impl empty_and_reset;
00130 };
00131 
00132 /*!
00133  * \brief General jitterbuffer state.
00134  */
00135 struct ast_jb
00136 {
00137    /*! \brief Jitterbuffer configuration. */
00138    struct ast_jb_conf conf;
00139    /*! \brief Jitterbuffer implementation to be used. */
00140    const struct ast_jb_impl *impl;
00141    /*! \brief Jitterbuffer object, passed to the implementation. */
00142    void *jbobj;
00143    /*! \brief The time the jitterbuffer was created. */
00144    struct timeval timebase;
00145    /*! \brief The time the next frame should be played. */
00146    long next;
00147    /*! \brief Voice format of the last frame in. */
00148    struct ast_format *last_format;
00149    /*! \brief File for frame timestamp tracing. */
00150    FILE *logfile;
00151    /*! \brief Jitterbuffer internal state flags. */
00152    unsigned int flags;
00153 };
00154 
00155 
00156 /*!
00157  * \brief Checks the need of a jb use in a generic bridge.
00158  * \param c0 first bridged channel.
00159  * \param c1 second bridged channel.
00160  *
00161  * Called from ast_generic_bridge() when two channels are entering in a bridge.
00162  * The function checks the need of a jitterbuffer, depending on both channel's
00163  * configuration and technology properties. As a result, this function sets
00164  * appropriate internal jb flags to the channels, determining further behaviour
00165  * of the bridged jitterbuffers.
00166  *
00167  * \retval zero if there are no jitter buffers in use
00168  * \retval non-zero if there are
00169  */
00170 int ast_jb_do_usecheck(struct ast_channel *c0, struct ast_channel *c1);
00171 
00172 
00173 /*!
00174  * \brief Calculates the time, left to the closest delivery moment in a bridge.
00175  * \param c0 first bridged channel.
00176  * \param c1 second bridged channel.
00177  * \param time_left bridge time limit, or -1 if not set.
00178  *
00179  * Called from ast_generic_bridge() to determine the maximum time to wait for
00180  * activity in ast_waitfor_n() call. If neihter of the channels is using jb,
00181  * this function returns the time limit passed.
00182  *
00183  * \return maximum time to wait.
00184  */
00185 int ast_jb_get_when_to_wakeup(struct ast_channel *c0, struct ast_channel *c1, int time_left);
00186 
00187 
00188 /*!
00189  * \brief Puts a frame into a channel jitterbuffer.
00190  * \param chan channel.
00191  * \param f frame.
00192  *
00193  * Called from ast_generic_bridge() to put a frame into a channel's jitterbuffer.
00194  * The function will successfuly enqueue a frame if and only if:
00195  * 1. the channel is using a jitterbuffer (as determined by ast_jb_do_usecheck()),
00196  * 2. the frame's type is AST_FRAME_VOICE,
00197  * 3. the frame has timing info set and has length >= 2 ms,
00198  * 4. there is no some internal error happened (like failed memory allocation).
00199  * Frames, successfuly queued, should be delivered by the channel's jitterbuffer,
00200  * when their delivery time has came.
00201  * Frames, not successfuly queued, should be delivered immediately.
00202  * Dropped by the jb implementation frames are considered successfuly enqueued as
00203  * far as they should not be delivered at all.
00204  *
00205  * \retval 0 if the frame was queued
00206  * \retval -1 if not
00207  */
00208 int ast_jb_put(struct ast_channel *chan, struct ast_frame *f);
00209 
00210 
00211 /*!
00212  * \brief Deliver the queued frames that should be delivered now for both channels.
00213  * \param c0 first bridged channel.
00214  * \param c1 second bridged channel.
00215  *
00216  * Called from ast_generic_bridge() to deliver any frames, that should be delivered
00217  * for the moment of invocation. Does nothing if neihter of the channels is using jb
00218  * or has any frames currently queued in. The function delivers frames usig ast_write()
00219  * each of the channels.
00220  */
00221 void ast_jb_get_and_deliver(struct ast_channel *c0, struct ast_channel *c1);
00222 
00223 
00224 /*!
00225  * \brief Destroys jitterbuffer on a channel.
00226  * \param chan channel.
00227  *
00228  * Called from ast_channel_free() when a channel is destroyed.
00229  */
00230 void ast_jb_destroy(struct ast_channel *chan);
00231 
00232 
00233 /*!
00234  * \brief Sets jitterbuffer configuration property.
00235  * \param conf configuration to store the property in.
00236  * \param varname property name.
00237  * \param value property value.
00238  *
00239  * Called from a channel driver to build a jitterbuffer configuration typically when
00240  * reading a configuration file. It is not necessary for a channel driver to know
00241  * each of the jb configuration property names. The jitterbuffer itself knows them.
00242  * The channel driver can pass each config var it reads through this function. It will
00243  * return 0 if the variable was consumed from the jb conf.
00244  *
00245  * \return zero if the property was set to the configuration, -1 if not.
00246  */
00247 int ast_jb_read_conf(struct ast_jb_conf *conf, const char *varname, const char *value);
00248 
00249 /*!
00250  * \since 12.0
00251  * \brief Sets a jitterbuffer frame hook on the channel based on the channel's stored
00252  *        jitterbuffer configuration
00253  *
00254  * \param chan Which channel is being set up
00255  */
00256 void ast_jb_enable_for_channel(struct ast_channel *chan);
00257 
00258 /*!
00259  * \brief Configures a jitterbuffer on a channel.
00260  * \param chan channel to configure.
00261  * \param conf configuration to apply.
00262  *
00263  * Called from a channel driver when a channel is created and its jitterbuffer needs
00264  * to be configured.
00265  */
00266 void ast_jb_configure(struct ast_channel *chan, const struct ast_jb_conf *conf);
00267 
00268 /*!
00269  * \brief Copies a channel's jitterbuffer configuration.
00270  * \param chan channel.
00271  * \param conf destination.
00272  */
00273 void ast_jb_get_config(const struct ast_channel *chan, struct ast_jb_conf *conf);
00274 
00275 /*!
00276  * \brief drops all frames from a jitterbuffer and resets it
00277  * \param c0 one channel of a bridge
00278  * \param c1 the other channel of the bridge
00279  */
00280 void ast_jb_empty_and_reset(struct ast_channel *c0, struct ast_channel *c1);
00281 
00282 const struct ast_jb_impl *ast_jb_get_impl(enum ast_jb_type type);
00283 
00284 /*!
00285  * \since 12
00286  * \brief Sets the contents of an ast_jb_conf struct to the default jitterbuffer settings
00287  *
00288  * \param conf Which jitterbuffer is being set
00289  */
00290 void ast_jb_conf_default(struct ast_jb_conf *conf);
00291 
00292 /*!
00293  * \since 12
00294  * \brief Applies a jitterbuffer framehook to a channel based on a provided jitterbuffer config
00295  *
00296  * \param chan Which channel the jitterbuffer is being set on
00297  * \param jb_conf Configuration to use for the jitterbuffer
00298  * \param prefer_existing If this is true and a jitterbuffer already exists for the channel,
00299  *        use the existing jitterbuffer
00300  */
00301 void ast_jb_create_framehook(struct ast_channel *chan, struct ast_jb_conf *jb_conf, int prefer_existing);
00302 
00303 #if defined(__cplusplus) || defined(c_plusplus)
00304 }
00305 #endif
00306 
00307 #endif /* _ABSTRACT_JB_H_ */

Generated on Thu Apr 16 06:27:05 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6