include/asterisk/audiohook.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 1999 - 2007, Digium, Inc.
   5  *
   6  * Joshua Colp <jcolp@digium.com>
   7  *
   8  * See http://www.asterisk.org for more information about
   9  * the Asterisk project. Please do not directly contact
  10  * any of the maintainers of this project for assistance;
  11  * the project provides a web site, mailing lists and IRC
  12  * channels for your use.
  13  *
  14  * This program is free software, distributed under the terms of
  15  * the GNU General Public License Version 2. See the LICENSE file
  16  * at the top of the source tree.
  17  */
  18
  19 /*! \file
  20  * \brief Audiohooks Architecture
  21  */
  22
  23 #ifndef _ASTERISK_AUDIOHOOK_H
  24 #define _ASTERISK_AUDIOHOOK_H
  25
  26 #if defined(__cplusplus) || defined(c_plusplus)
  27 extern "C" {
  28 #endif
  29
  30 /* these two are used in struct ast_audiohook */
  31 #include "asterisk/lock.h"
  32 #include "asterisk/linkedlists.h"
  33
  34 #include "asterisk/slinfactory.h"
  35
  36 enum ast_audiohook_type {
  37         AST_AUDIOHOOK_TYPE_SPY = 0,    /*!< Audiohook wants to receive audio */
  38         AST_AUDIOHOOK_TYPE_WHISPER,    /*!< Audiohook wants to provide audio to be mixed with existing audio */
  39         AST_AUDIOHOOK_TYPE_MANIPULATE, /*!< Audiohook wants to manipulate the audio */
  40 };
  41
  42 enum ast_audiohook_status {
  43         AST_AUDIOHOOK_STATUS_NEW = 0,  /*!< Audiohook was just created, not in use yet */
  44         AST_AUDIOHOOK_STATUS_RUNNING,  /*!< Audiohook is running on a channel */
  45         AST_AUDIOHOOK_STATUS_SHUTDOWN, /*!< Audiohook is being shutdown */
  46         AST_AUDIOHOOK_STATUS_DONE,     /*!< Audiohook has shutdown and is not running on a channel any longer */
  47 };
  48
  49 enum ast_audiohook_direction {
  50         AST_AUDIOHOOK_DIRECTION_READ = 0, /*!< Reading audio in */
  51         AST_AUDIOHOOK_DIRECTION_WRITE,    /*!< Writing audio out */
  52         AST_AUDIOHOOK_DIRECTION_BOTH,     /*!< Both reading audio in and writing audio out */
  53 };
  54
  55 enum ast_audiohook_flags {
  56         AST_AUDIOHOOK_TRIGGER_MODE = (3 << 0),  /*!< When audiohook should be triggered to do something */
  57         AST_AUDIOHOOK_TRIGGER_READ = (1 << 0),  /*!< Audiohook wants to be triggered when reading audio in */
  58         AST_AUDIOHOOK_TRIGGER_WRITE = (2 << 0), /*!< Audiohook wants to be triggered when writing audio out */
  59         AST_AUDIOHOOK_WANTS_DTMF = (1 << 1),    /*!< Audiohook also wants to receive DTMF frames */
  60         AST_AUDIOHOOK_TRIGGER_SYNC = (1 << 2),  /*!< Audiohook wants to be triggered when both sides have combined audio available */
  61 };
  62
  63 #define AST_AUDIOHOOK_SYNC_TOLERANCE 100 /*< Tolerance in milliseconds for audiohooks synchronization */
  64
  65 struct ast_audiohook;
  66
  67 /*! \brief Callback function for manipulate audiohook type
  68  * \param audiohook Audiohook structure
  69  * \param chan Channel
  70  * \param frame Frame of audio to manipulate
  71  * \param direction Direction frame came from
  72  * \return Returns 0 on success, -1 on failure
  73  * \note An audiohook does not have any reference to a private data structure for manipulate types. It is up to the manipulate callback to store this data
  74  *       via it's own method. An example would be datastores.
  75  */
  76 typedef int (*ast_audiohook_manipulate_callback)(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction);
  77
  78 struct ast_audiohook_options {
  79         int read_volume;  /*!< Volume adjustment on frames read from the channel the hook is on */
  80         int write_volume; /*!< Volume adjustment on frames written to the channel the hook is on */
  81 };
  82
  83 struct ast_audiohook {
  84         ast_mutex_t lock;                                      /*!< Lock that protects the audiohook structure */
  85         ast_cond_t trigger;                                    /*!< Trigger condition (if enabled) */
  86         enum ast_audiohook_type type;                          /*!< Type of audiohook */
  87         enum ast_audiohook_status status;                      /*!< Status of the audiohook */
  88         const char *source;                                    /*!< Who this audiohook ultimately belongs to */
  89         unsigned int flags;                                    /*!< Flags on the audiohook */
  90         struct ast_slinfactory read_factory;                   /*!< Factory where frames read from the channel, or read from the whisper source will go through */
  91         struct ast_slinfactory write_factory;                  /*!< Factory where frames written to the channel will go through */
  92         struct timeval read_time;                              /*!< Last time read factory was fed */
  93         struct timeval write_time;                             /*!< Last time write factory was fed */
  94         int format;                                            /*!< Format translation path is setup as */
  95         struct ast_trans_pvt *trans_pvt;                       /*!< Translation path for reading frames */
  96         ast_audiohook_manipulate_callback manipulate_callback; /*!< Manipulation callback */
  97         struct ast_audiohook_options options;                  /*!< Applicable options */
  98         AST_LIST_ENTRY(ast_audiohook) list;                    /*!< Linked list information */
  99 };
 100
 101 struct ast_audiohook_list;
 102
 103 /*! \brief Initialize an audiohook structure
 104  * \param audiohook Audiohook structure
 105  * \param type Type of audiohook to initialize this as
 106  * \param source Who is initializing this audiohook
 107  * \return Returns 0 on success, -1 on failure
 108  */
 109 int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source);
 110
 111 /*! \brief Destroys an audiohook structure
 112  * \param audiohook Audiohook structure
 113  * \return Returns 0 on success, -1 on failure
 114  */
 115 int ast_audiohook_destroy(struct ast_audiohook *audiohook);
 116
 117 /*! \brief Writes a frame into the audiohook structure
 118  * \param audiohook Audiohook structure
 119  * \param direction Direction the audio frame came from
 120  * \param frame Frame to write in
 121  * \return Returns 0 on success, -1 on failure
 122  */
 123 int ast_audiohook_write_frame(struct ast_audiohook *audiohook, enum ast_audiohook_direction direction, struct ast_frame *frame);
 124
 125 /*! \brief Reads a frame in from the audiohook structure
 126  * \param audiohook Audiohook structure
 127  * \param samples Number of samples wanted
 128  * \param direction Direction the audio frame came from
 129  * \param format Format of frame remote side wants back
 130  * \return Returns frame on success, NULL on failure
 131  */
 132 struct ast_frame *ast_audiohook_read_frame(struct ast_audiohook *audiohook, size_t samples, enum ast_audiohook_direction direction, int format);
 133
 134 /*! \brief Attach audiohook to channel
 135  * \param chan Channel
 136  * \param audiohook Audiohook structure
 137  * \return Returns 0 on success, -1 on failure
 138  */
 139 int ast_audiohook_attach(struct ast_channel *chan, struct ast_audiohook *audiohook);
 140
 141 /*! \brief Detach audiohook from channel
 142  * \param audiohook Audiohook structure
 143  * \return Returns 0 on success, -1 on failure
 144  */
 145 int ast_audiohook_detach(struct ast_audiohook *audiohook);
 146
 147 /*! \brief Detach audiohooks from list and destroy said list
 148  * \param audiohook_list List of audiohooks
 149  * \return Returns 0 on success, -1 on failure
 150  */
 151 int ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list);
 152
 153 /*! \brief Move an audiohook from one channel to a new one
 154  *
 155  * \todo Currently only the first audiohook of a specific source found will be moved.
 156  * We should add the capability to move multiple audiohooks from a single source as well.
 157  *
 158  * \note It is required that both old_chan and new_chan are locked prior to calling
 159  * this function. Besides needing to protect the data within the channels, not locking
 160  * these channels can lead to a potential deadlock
 161  *
 162  * \param old_chan The source of the audiohook to move
 163  * \param new_chan The destination to which we want the audiohook to move
 164  * \param source The source of the audiohook we want to move
 165  */
 166 void ast_audiohook_move_by_source(struct ast_channel *old_chan, struct ast_channel *new_chan, const char *source);
 167
 168 /*!
 169  * \brief Detach specified source audiohook from channel
 170  *
 171  * \param chan Channel to detach from
 172  * \param source Name of source to detach
 173  *
 174  * \return Returns 0 on success, -1 on failure
 175  *
 176  * \note The channel does not need to be locked before calling this function.
 177  */
 178 int ast_audiohook_detach_source(struct ast_channel *chan, const char *source);
 179
 180 /*!
 181  * \brief Remove an audiohook from a specified channel
 182  *
 183  * \param chan Channel to remove from
 184  * \param audiohook Audiohook to remove
 185  *
 186  * \return Returns 0 on success, -1 on failure
 187  *
 188  * \note The channel does not need to be locked before calling this function
 189  */
 190 int ast_audiohook_remove(struct ast_channel *chan, struct ast_audiohook *audiohook);
 191
 192 /*! \brief Pass a frame off to be handled by the audiohook core
 193  * \param chan Channel that the list is coming off of
 194  * \param audiohook_list List of audiohooks
 195  * \param direction Direction frame is coming in from
 196  * \param frame The frame itself
 197  * \return Return frame on success, NULL on failure
 198  */
 199 struct ast_frame *ast_audiohook_write_list(struct ast_channel *chan, struct ast_audiohook_list *audiohook_list, enum ast_audiohook_direction direction, struct ast_frame *frame);
 200
 201 /*! \brief Wait for audiohook trigger to be triggered
 202  * \param audiohook Audiohook to wait on
 203  */
 204 void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook);
 205
 206 /*!
 207   \brief Find out how many audiohooks from  a certain source exist on a given channel, regardless of status.
 208   \param chan The channel on which to find the spies
 209   \param source The audiohook's source
 210   \param type The type of audiohook
 211   \return Return the number of audiohooks which are from the source specified
 212
 213   Note: Function performs nlocking.
 214 */
 215 int ast_channel_audiohook_count_by_source(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
 216
 217 /*!
 218   \brief Find out how many spies of a certain type exist on a given channel, and are in state running.
 219   \param chan The channel on which to find the spies
 220   \param source The source of the audiohook
 221   \param type The type of spy to look for
 222   \return Return the number of running audiohooks which are from the source specified
 223
 224   Note: Function performs no locking.
 225 */
 226 int ast_channel_audiohook_count_by_source_running(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
 227
 228 /*! \brief Lock an audiohook
 229  * \param ah Audiohook structure
 230  */
 231 #define ast_audiohook_lock(ah) ast_mutex_lock(&(ah)->lock)
 232
 233 /*! \brief Unlock an audiohook
 234  * \param ah Audiohook structure
 235  */
 236 #define ast_audiohook_unlock(ah) ast_mutex_unlock(&(ah)->lock)
 237
 238 /*! \brief Adjust the volume on frames read from or written to a channel
 239  * \param chan Channel to muck with
 240  * \param direction Direction to set on
 241  * \param volume Value to adjust the volume by
 242  * \return Returns 0 on success, -1 on failure
 243  */
 244 int ast_audiohook_volume_set(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
 245
 246 /*! \brief Retrieve the volume adjustment value on frames read from or written to a channel
 247  * \param chan Channel to retrieve volume adjustment from
 248  * \param direction Direction to retrieve
 249  * \return Returns adjustment value
 250  */
 251 int ast_audiohook_volume_get(struct ast_channel *chan, enum ast_audiohook_direction direction);
 252
 253 /*! \brief Adjust the volume on frames read from or written to a channel
 254  * \param chan Channel to muck with
 255  * \param direction Direction to increase
 256  * \param volume Value to adjust the adjustment by
 257  * \return Returns 0 on success, -1 on failure
 258  */
 259 int ast_audiohook_volume_adjust(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
 260
 261 #if defined(__cplusplus) || defined(c_plusplus)
 262 }
 263 #endif
 264
 265 #endif /* _ASTERISK_AUDIOHOOK_H */