Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:47:53 2009

## Asterisk developer's documentation

# chanspy.h

Go to the documentation of this file.

    00001 /*
    00002  * Asterisk -- An open source telephony toolkit.
    00003  *
    00004  * Copyright (C) 1999 - 2005, Digium, Inc.
    00005  *
    00006  * Mark Spencer <markster@digium.com>
    00007  *
    00008  * See http://www.asterisk.org for more information about
    00009  * the Asterisk project. Please do not directly contact
    00010  * any of the maintainers of this project for assistance;
    00011  * the project provides a web site, mailing lists and IRC
    00012  * channels for your use.
    00013  *
    00014  * This program is free software, distributed under the terms of
    00015  * the GNU General Public License Version 2. See the LICENSE file
    00016  * at the top of the source tree.
    00017  */
    00018
    00019 /*! \file
    00020  * \brief Asterisk PBX channel spy definitions
    00021  */
    00022
    00023 #ifndef _ASTERISK_CHANSPY_H
    00024 #define _ASTERISK_CHANSPY_H
    00025
    00026 #if defined(__cplusplus) || defined(c_plusplus)
    00027 extern "C" {
    00028 #endif
    00029
    00030 #include "asterisk/linkedlists.h"
    00031
    00032 enum chanspy_states {
    00033    CHANSPY_NEW = 0,     /*!< spy not yet operating */
    00034    CHANSPY_RUNNING = 1,    /*!< normal operation, spy is still operating */
    00035    CHANSPY_DONE = 2,    /*!< spy is stopped and already removed from channel */
    00036    CHANSPY_STOP = 3,    /*!< spy requested to stop, still attached to channel */
    00037 };
    00038
    00039 enum chanspy_flags {
    00040    CHANSPY_MIXAUDIO = (1 << 0),
    00041    CHANSPY_READ_VOLADJUST = (1 << 1),
    00042    CHANSPY_WRITE_VOLADJUST = (1 << 2),
    00043    CHANSPY_FORMAT_AUDIO = (1 << 3),
    00044    CHANSPY_TRIGGER_MODE = (3 << 4),
    00045    CHANSPY_TRIGGER_READ = (1 << 4),
    00046    CHANSPY_TRIGGER_WRITE = (2 << 4),
    00047    CHANSPY_TRIGGER_NONE = (3 << 4),
    00048    CHANSPY_TRIGGER_FLUSH = (1 << 6),
    00049 };
    00050
    00051 struct ast_channel_spy_queue {
    00052    struct ast_frame *head;
    00053    unsigned int samples;
    00054    unsigned int format;
    00055 };
    00056
    00057 struct ast_channel_spy {
    00058    AST_LIST_ENTRY(ast_channel_spy) list;
    00059    ast_mutex_t lock;
    00060    ast_cond_t trigger;
    00061    struct ast_channel *chan;
    00062    struct ast_channel_spy_queue read_queue;
    00063    struct ast_channel_spy_queue write_queue;
    00064    unsigned int flags;
    00065    enum chanspy_states status;
    00066    const char *type;
    00067    /* The volume adjustment values are very straightforward:
    00068       positive values cause the samples to be multiplied by that amount
    00069       negative values cause the samples to be divided by the absolute value of that amount
    00070    */
    00071    int read_vol_adjustment;
    00072    int write_vol_adjustment;
    00073 };
    00074
    00075 /*!
    00076   \brief Adds a spy to a channel, to begin receiving copies of the channel's audio frames.
    00077   \param chan The channel to add the spy to.
    00078   \param spy A pointer to ast_channel_spy structure describing how the spy is to be used.
    00079   \return 0 for success, non-zero for failure
    00080
    00081   Note: This function performs no locking; you must hold the channel's lock before
    00082   calling this function.
    00083  */
    00084 int ast_channel_spy_add(struct ast_channel *chan, struct ast_channel_spy *spy);
    00085
    00086 /*!
    00087   \brief Remove a spy from a channel.
    00088   \param chan The channel to remove the spy from
    00089   \param spy The spy to be removed
    00090   \return nothing
    00091
    00092   Note: This function performs no locking; you must hold the channel's lock before
    00093   calling this function.
    00094  */
    00095 void ast_channel_spy_remove(struct ast_channel *chan, struct ast_channel_spy *spy);
    00096
    00097 /*!
    00098   \brief Free a spy.
    00099   \param spy The spy to free
    00100   \return nothing
    00101
    00102   Note: This function MUST NOT be called with the spy locked.
    00103 */
    00104 void ast_channel_spy_free(struct ast_channel_spy *spy);
    00105
    00106 /*!
    00107   \brief Find all spies of a particular type on a channel and stop them.
    00108   \param chan The channel to operate on
    00109   \param type A character string identifying the type of spies to be stopped
    00110   \return nothing
    00111
    00112   Note: This function performs no locking; you must hold the channel's lock before
    00113   calling this function.
    00114  */
    00115 void ast_channel_spy_stop_by_type(struct ast_channel *chan, const char *type);
    00116
    00117 /*!
    00118   \brief Read one (or more) frames of audio from a channel being spied upon.
    00119   \param spy The spy to operate on
    00120   \param samples The number of audio samples to read
    00121   \return NULL for failure, one ast_frame pointer, or a chain of ast_frame pointers
    00122
    00123   This function can return multiple frames if the spy structure needs to be 'flushed'
    00124   due to mismatched queue lengths, or if the spy structure is configured to return
    00125   unmixed audio (in which case each call to this function will return a frame of audio
    00126   from each side of channel).
    00127
    00128   Note: This function performs no locking; you must hold the spy's lock before calling
    00129   this function. You must <b>not</b> hold the channel's lock at the same time.
    00130  */
    00131 struct ast_frame *ast_channel_spy_read_frame(struct ast_channel_spy *spy, unsigned int samples);
    00132
    00133 /*!
    00134   \brief Efficiently wait until audio is available for a spy, or an exception occurs.
    00135   \param spy The spy to wait on
    00136   \return nothing
    00137
    00138   Note: The locking rules for this function are non-obvious... first, you must <b>not</b>
    00139   hold the channel's lock when calling this function. Second, you must hold the spy's lock
    00140   before making the function call; while the function runs the lock will be released, and
    00141   when the trigger event occurs, the lock will be re-obtained. This means that when control
    00142   returns to your code, you will again hold the spy's lock.
    00143  */
    00144 void ast_channel_spy_trigger_wait(struct ast_channel_spy *spy);
    00145
    00146 #if defined(__cplusplus) || defined(c_plusplus)
    00147 }
    00148 #endif
    00149
    00150 #endif /* _ASTERISK_CHANSPY_H */