Wed Apr 6 11:29:37 2011

Asterisk developer's documentation


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/frame_defs.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 #define AST_JB_IMPL_NAME_SIZE 12
00051 
00052 /*!
00053  * \brief General jitterbuffer configuration.
00054  */
00055 struct ast_jb_conf
00056 {
00057    /*! \brief Combination of the AST_JB_ENABLED, AST_JB_FORCED and AST_JB_LOG flags. */
00058    unsigned int flags;
00059    /*! \brief Max size of the jitterbuffer implementation. */
00060    long max_size;
00061    /*! \brief Resynchronization threshold of the jitterbuffer implementation. */
00062    long resync_threshold;
00063    /*! \brief Name of the jitterbuffer implementation to be used. */
00064    char impl[AST_JB_IMPL_NAME_SIZE];
00065    /*! \brief amount of additional jitterbuffer adjustment */
00066    long target_extra;
00067 };
00068 
00069 
00070 /* Jitterbuffer configuration property names */
00071 #define AST_JB_CONF_PREFIX "jb"
00072 #define AST_JB_CONF_ENABLE "enable"
00073 #define AST_JB_CONF_FORCE "force"
00074 #define AST_JB_CONF_MAX_SIZE "maxsize"
00075 #define AST_JB_CONF_RESYNCH_THRESHOLD "resyncthreshold"
00076 #define AST_JB_CONF_TARGET_EXTRA "targetextra"
00077 #define AST_JB_CONF_IMPL "impl"
00078 #define AST_JB_CONF_LOG "log"
00079 
00080 
00081 struct ast_jb_impl;
00082 
00083 
00084 /*!
00085  * \brief General jitterbuffer state.
00086  */
00087 struct ast_jb
00088 {
00089    /*! \brief Jitterbuffer configuration. */
00090    struct ast_jb_conf conf;
00091    /*! \brief Jitterbuffer implementation to be used. */
00092    const struct ast_jb_impl *impl;
00093    /*! \brief Jitterbuffer object, passed to the implementation. */
00094    void *jbobj;
00095    /*! \brief The time the jitterbuffer was created. */
00096    struct timeval timebase;
00097    /*! \brief The time the next frame should be played. */
00098    long next;
00099    /*! \brief Voice format of the last frame in. */
00100    format_t last_format;
00101    /*! \brief File for frame timestamp tracing. */
00102    FILE *logfile;
00103    /*! \brief Jitterbuffer internal state flags. */
00104    unsigned int flags;
00105 };
00106 
00107 
00108 /*!
00109  * \brief Checks the need of a jb use in a generic bridge.
00110  * \param c0 first bridged channel.
00111  * \param c1 second bridged channel.
00112  *
00113  * Called from ast_generic_bridge() when two channels are entering in a bridge.
00114  * The function checks the need of a jitterbuffer, depending on both channel's
00115  * configuration and technology properties. As a result, this function sets
00116  * appropriate internal jb flags to the channels, determining further behaviour
00117  * of the bridged jitterbuffers.
00118  *
00119  * \retval zero if there are no jitter buffers in use
00120  * \retval non-zero if there are
00121  */
00122 int ast_jb_do_usecheck(struct ast_channel *c0, struct ast_channel *c1);
00123 
00124 
00125 /*!
00126  * \brief Calculates the time, left to the closest delivery moment in a bridge.
00127  * \param c0 first bridged channel.
00128  * \param c1 second bridged channel.
00129  * \param time_left bridge time limit, or -1 if not set.
00130  *
00131  * Called from ast_generic_bridge() to determine the maximum time to wait for
00132  * activity in ast_waitfor_n() call. If neihter of the channels is using jb,
00133  * this function returns the time limit passed.
00134  *
00135  * \return maximum time to wait.
00136  */
00137 int ast_jb_get_when_to_wakeup(struct ast_channel *c0, struct ast_channel *c1, int time_left);
00138 
00139 
00140 /*!
00141  * \brief Puts a frame into a channel jitterbuffer.
00142  * \param chan channel.
00143  * \param f frame.
00144  *
00145  * Called from ast_generic_bridge() to put a frame into a channel's jitterbuffer.
00146  * The function will successfuly enqueue a frame if and only if:
00147  * 1. the channel is using a jitterbuffer (as determined by ast_jb_do_usecheck()),
00148  * 2. the frame's type is AST_FRAME_VOICE,
00149  * 3. the frame has timing info set and has length >= 2 ms,
00150  * 4. there is no some internal error happened (like failed memory allocation).
00151  * Frames, successfuly queued, should be delivered by the channel's jitterbuffer,
00152  * when their delivery time has came.
00153  * Frames, not successfuly queued, should be delivered immediately.
00154  * Dropped by the jb implementation frames are considered successfuly enqueued as
00155  * far as they should not be delivered at all.
00156  *
00157  * \retval 0 if the frame was queued
00158  * \retval -1 if not
00159  */
00160 int ast_jb_put(struct ast_channel *chan, struct ast_frame *f);
00161 
00162 
00163 /*!
00164  * \brief Deliver the queued frames that should be delivered now for both channels.
00165  * \param c0 first bridged channel.
00166  * \param c1 second bridged channel.
00167  *
00168  * Called from ast_generic_bridge() to deliver any frames, that should be delivered
00169  * for the moment of invocation. Does nothing if neihter of the channels is using jb
00170  * or has any frames currently queued in. The function delivers frames usig ast_write()
00171  * each of the channels.
00172  */
00173 void ast_jb_get_and_deliver(struct ast_channel *c0, struct ast_channel *c1);
00174 
00175 
00176 /*!
00177  * \brief Destroys jitterbuffer on a channel.
00178  * \param chan channel.
00179  *
00180  * Called from ast_channel_free() when a channel is destroyed.
00181  */
00182 void ast_jb_destroy(struct ast_channel *chan);
00183 
00184 
00185 /*!
00186  * \brief Sets jitterbuffer configuration property.
00187  * \param conf configuration to store the property in.
00188  * \param varname property name.
00189  * \param value property value.
00190  *
00191  * Called from a channel driver to build a jitterbuffer configuration typically when
00192  * reading a configuration file. It is not necessary for a channel driver to know
00193  * each of the jb configuration property names. The jitterbuffer itself knows them.
00194  * The channel driver can pass each config var it reads through this function. It will
00195  * return 0 if the variable was consumed from the jb conf.
00196  *
00197  * \return zero if the property was set to the configuration, -1 if not.
00198  */
00199 int ast_jb_read_conf(struct ast_jb_conf *conf, const char *varname, const char *value);
00200 
00201 
00202 /*!
00203  * \brief Configures a jitterbuffer on a channel.
00204  * \param chan channel to configure.
00205  * \param conf configuration to apply.
00206  *
00207  * Called from a channel driver when a channel is created and its jitterbuffer needs
00208  * to be configured.
00209  */
00210 void ast_jb_configure(struct ast_channel *chan, const struct ast_jb_conf *conf);
00211 
00212 
00213 /*!
00214  * \brief Copies a channel's jitterbuffer configuration.
00215  * \param chan channel.
00216  * \param conf destination.
00217  */
00218 void ast_jb_get_config(const struct ast_channel *chan, struct ast_jb_conf *conf);
00219 
00220 /*!
00221  * \brief drops all frames from a jitterbuffer and resets it
00222  * \param c0 one channel of a bridge
00223  * \param c1 the other channel of the bridge
00224  */
00225 void ast_jb_empty_and_reset(struct ast_channel *c0, struct ast_channel *c1);
00226 
00227 #if defined(__cplusplus) || defined(c_plusplus)
00228 }
00229 #endif
00230 
00231 #endif /* _ABSTRACT_JB_H_ */

Generated on Wed Apr 6 11:29:37 2011 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7