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 #include "asterisk/slinfactory.h"
  34
  35 enum ast_audiohook_type {
  36         AST_AUDIOHOOK_TYPE_SPY = 0,    /*!< Audiohook wants to receive audio */
  37         AST_AUDIOHOOK_TYPE_WHISPER,    /*!< Audiohook wants to provide audio to be mixed with existing audio */
  38         AST_AUDIOHOOK_TYPE_MANIPULATE, /*!< Audiohook wants to manipulate the audio */
  39 };
  40
  41 enum ast_audiohook_status {
  42         AST_AUDIOHOOK_STATUS_NEW = 0,  /*!< Audiohook was just created, not in use yet */
  43         AST_AUDIOHOOK_STATUS_RUNNING,  /*!< Audiohook is running on a channel */
  44         AST_AUDIOHOOK_STATUS_SHUTDOWN, /*!< Audiohook is being shutdown */
  45         AST_AUDIOHOOK_STATUS_DONE,     /*!< Audiohook has shutdown and is not running on a channel any longer */
  46 };
  47
  48 enum ast_audiohook_direction {
  49         AST_AUDIOHOOK_DIRECTION_READ = 0, /*!< Reading audio in */
  50         AST_AUDIOHOOK_DIRECTION_WRITE,    /*!< Writing audio out */
  51         AST_AUDIOHOOK_DIRECTION_BOTH,     /*!< Both reading audio in and writing audio out */
  52 };
  53
  54 enum ast_audiohook_flags {
  55         AST_AUDIOHOOK_TRIGGER_MODE  = (3 << 0), /*!< When audiohook should be triggered to do something */
  56         AST_AUDIOHOOK_TRIGGER_READ  = (1 << 0), /*!< Audiohook wants to be triggered when reading audio in */
  57         AST_AUDIOHOOK_TRIGGER_WRITE = (2 << 0), /*!< Audiohook wants to be triggered when writing audio out */
  58         AST_AUDIOHOOK_WANTS_DTMF    = (1 << 2), /*!< Audiohook also wants to receive DTMF frames */
  59         AST_AUDIOHOOK_TRIGGER_SYNC  = (1 << 3), /*!< Audiohook wants to be triggered when both sides have combined audio available */
  60         /*! Audiohooks with this flag set will not allow for a large amount of samples to build up on its
  61          * slinfactories. We will flush the factories if they contain too many samples.
  62          */
  63         AST_AUDIOHOOK_SMALL_QUEUE   = (1 << 4),
  64         AST_AUDIOHOOK_MUTE_READ     = (1 << 5), /*!< audiohook should be mute frames read */
  65         AST_AUDIOHOOK_MUTE_WRITE    = (1 << 6), /*!< audiohook should be mute frames written */
  66         AST_AUDIOHOOK_COMPATIBLE    = (1 << 7), /*!< is the audiohook native slin compatible */
  67 };
  68
  69 enum ast_audiohook_init_flags {
  70         /*! Audiohook manipulate callback is capable of handling slinear at any sample rate.
  71          * Without enabling this flag on initialization the manipulation callback is guaranteed
  72          * 8khz audio only. */
  73         AST_AUDIOHOOK_MANIPULATE_ALL_RATES = (1 << 0),
  74 };
  75
  76 struct ast_audiohook;
  77
  78 /*! \brief Callback function for manipulate audiohook type
  79  * \param audiohook Audiohook structure
  80  * \param chan Channel
  81  * \param frame Frame of audio to manipulate
  82  * \param direction Direction frame came from
  83  * \return Returns 0 on success, -1 on failure.
  84  * \note An audiohook does not have any reference to a private data structure for manipulate
  85  *       types. It is up to the manipulate callback to store this data via it's own method.
  86  *       An example would be datastores.
  87  * \note The input frame should never be freed or corrupted during a manipulate callback.
  88  *       If the callback has the potential to corrupt the frame's data during manipulation,
  89  *       local data should be used for the manipulation and only copied to the frame on
  90  *       success.
  91  * \note A failure return value indicates that the frame was not manipulated and that
  92  *       is being returned in its original state.
  93  */
  94 typedef int (*ast_audiohook_manipulate_callback)(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction);
  95
  96 struct ast_audiohook_options {
  97         int read_volume;  /*!< Volume adjustment on frames read from the channel the hook is on */
  98         int write_volume; /*!< Volume adjustment on frames written to the channel the hook is on */
  99 };
 100
 101 struct ast_audiohook {
 102         ast_mutex_t lock;                                      /*!< Lock that protects the audiohook structure */
 103         ast_cond_t trigger;                                    /*!< Trigger condition (if enabled) */
 104         enum ast_audiohook_type type;                          /*!< Type of audiohook */
 105         enum ast_audiohook_status status;                      /*!< Status of the audiohook */
 106         enum ast_audiohook_init_flags init_flags;              /*!< Init flags */
 107         const char *source;                                    /*!< Who this audiohook ultimately belongs to */
 108         unsigned int flags;                                    /*!< Flags on the audiohook */
 109         struct ast_slinfactory read_factory;                   /*!< Factory where frames read from the channel, or read from the whisper source will go through */
 110         struct ast_slinfactory write_factory;                  /*!< Factory where frames written to the channel will go through */
 111         struct timeval read_time;                              /*!< Last time read factory was fed */
 112         struct timeval write_time;                             /*!< Last time write factory was fed */
 113         struct ast_format *format;                             /*!< Format translation path is setup as */
 114         struct ast_trans_pvt *trans_pvt;                       /*!< Translation path for reading frames */
 115         ast_audiohook_manipulate_callback manipulate_callback; /*!< Manipulation callback */
 116         struct ast_audiohook_options options;                  /*!< Applicable options */
 117         unsigned int hook_internal_samp_rate;                           /*!< internal read/write sample rate on the audiohook.*/
 118         AST_LIST_ENTRY(ast_audiohook) list;                    /*!< Linked list information */
 119 };
 120
 121 struct ast_audiohook_list;
 122
 123 /*! \brief Initialize an audiohook structure
 124  * \param audiohook Audiohook structure
 125  * \param type Type of audiohook to initialize this as
 126  * \param source Who is initializing this audiohook
 127  * \param init flags
 128  * \return Returns 0 on success, -1 on failure
 129  */
 130 int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source, enum ast_audiohook_init_flags flags);
 131
 132 /*! \brief Destroys an audiohook structure
 133  * \param audiohook Audiohook structure
 134  * \return Returns 0 on success, -1 on failure
 135  */
 136 int ast_audiohook_destroy(struct ast_audiohook *audiohook);
 137
 138 /*! \brief Writes a frame into the audiohook structure
 139  * \param audiohook Audiohook structure
 140  * \param direction Direction the audio frame came from
 141  * \param frame Frame to write in
 142  * \return Returns 0 on success, -1 on failure
 143  */
 144 int ast_audiohook_write_frame(struct ast_audiohook *audiohook, enum ast_audiohook_direction direction, struct ast_frame *frame);
 145
 146 /*! \brief Reads a frame in from the audiohook structure
 147  * \param audiohook Audiohook structure
 148  * \param samples Number of samples wanted
 149  * \param direction Direction the audio frame came from
 150  * \param format Format of frame remote side wants back
 151  * \return Returns frame on success, NULL on failure
 152  */
 153 struct ast_frame *ast_audiohook_read_frame(struct ast_audiohook *audiohook, size_t samples, enum ast_audiohook_direction direction, struct ast_format *format);
 154
 155 /*! \brief Reads a frame in from the audiohook structure in mixed audio mode and copies read and write frame data to provided arguments.
 156  * \param audiohook Audiohook structure
 157  * \param samples Number of samples wanted
 158  * \param ast_format Format of frame remote side wants back
 159  * \param read_frame if available, we'll copy the read buffer to this.
 160  * \param write_frame if available, we'll copy the write buffer to this.
 161  * \param direction
 162  * \return Returns frame on success, NULL on failure
 163  */
 164 struct ast_frame *ast_audiohook_read_frame_all(struct ast_audiohook *audiohook, size_t samples, struct ast_format *format, struct ast_frame **read_frame, struct ast_frame **write_frame);
 165
 166 /*! \brief Attach audiohook to channel
 167  * \param chan Channel
 168  * \param audiohook Audiohook structure
 169  * \return Returns 0 on success, -1 on failure
 170  */
 171 int ast_audiohook_attach(struct ast_channel *chan, struct ast_audiohook *audiohook);
 172
 173 /*! \brief Detach audiohook from channel
 174  * \param audiohook Audiohook structure
 175  * \return Returns 0 on success, -1 on failure
 176  */
 177 int ast_audiohook_detach(struct ast_audiohook *audiohook);
 178
 179 /*!
 180  * \brief Detach audiohooks from list and destroy said list
 181  * \param audiohook_list List of audiohooks (NULL tolerant)
 182  * \return Nothing
 183  */
 184 void ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list);
 185
 186 /*! \brief Move an audiohook from one channel to a new one
 187  *
 188  * \todo Currently only the first audiohook of a specific source found will be moved.
 189  * We should add the capability to move multiple audiohooks from a single source as well.
 190  *
 191  * \note It is required that both old_chan and new_chan are locked prior to calling
 192  * this function. Besides needing to protect the data within the channels, not locking
 193  * these channels can lead to a potential deadlock
 194  *
 195  * \param old_chan The source of the audiohook to move
 196  * \param new_chan The destination to which we want the audiohook to move
 197  * \param source The source of the audiohook we want to move
 198  */
 199 void ast_audiohook_move_by_source(struct ast_channel *old_chan, struct ast_channel *new_chan, const char *source);
 200
 201 /*! \brief Move all audiohooks from one channel to another
 202  *
 203  * \note It is required that both old_chan and new_chan are locked prior to calling
 204  * this function. Besides needing to protect the data within the channels, not locking
 205  * these channels can lead to a potential deadlock.
 206  *
 207  * \param old_chan The source of the audiohooks being moved
 208  * \param new_chan The destination channel for the audiohooks to be moved to
 209  */
 210 void ast_audiohook_move_all(struct ast_channel *old_chan, struct ast_channel *new_chan);
 211
 212 /*!
 213  * \brief Detach specified source audiohook from channel
 214  *
 215  * \param chan Channel to detach from
 216  * \param source Name of source to detach
 217  *
 218  * \return Returns 0 on success, -1 on failure
 219  *
 220  * \note The channel does not need to be locked before calling this function.
 221  */
 222 int ast_audiohook_detach_source(struct ast_channel *chan, const char *source);
 223
 224 /*!
 225  * \brief Remove an audiohook from a specified channel
 226  *
 227  * \param chan Channel to remove from
 228  * \param audiohook Audiohook to remove
 229  *
 230  * \return Returns 0 on success, -1 on failure
 231  *
 232  * \note The channel does not need to be locked before calling this function
 233  */
 234 int ast_audiohook_remove(struct ast_channel *chan, struct ast_audiohook *audiohook);
 235
 236 /*!
 237  * \brief Determine if a audiohook_list is empty or not.
 238  *
 239  * \param audiohook Audiohook to check.  (NULL also means empty)
 240  *
 241  * retval 0 false, 1 true
 242  */
 243 int ast_audiohook_write_list_empty(struct ast_audiohook_list *audiohook_list);
 244
 245 /*! \brief Pass a frame off to be handled by the audiohook core
 246  * \param chan Channel that the list is coming off of
 247  * \param audiohook_list List of audiohooks
 248  * \param direction Direction frame is coming in from
 249  * \param frame The frame itself
 250  * \return Return frame on success, NULL on failure
 251  */
 252 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);
 253
 254 /*! \brief Update audiohook's status
 255  * \param audiohook Audiohook structure
 256  * \param audiohook status enum
 257  *
 258  * \note once status is updated to DONE, this function can not be used to set the
 259  * status back to any other setting.  Setting DONE effectively locks the status as such.
 260  */
 261 void ast_audiohook_update_status(struct ast_audiohook *audiohook, enum ast_audiohook_status status);
 262
 263 /*! \brief Wait for audiohook trigger to be triggered
 264  * \param audiohook Audiohook to wait on
 265  */
 266 void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook);
 267
 268 /*!
 269   \brief Find out how many audiohooks from  a certain source exist on a given channel, regardless of status.
 270   \param chan The channel on which to find the spies
 271   \param source The audiohook's source
 272   \param type The type of audiohook
 273   \return Return the number of audiohooks which are from the source specified
 274
 275   Note: Function performs nlocking.
 276 */
 277 int ast_channel_audiohook_count_by_source(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
 278
 279 /*!
 280   \brief Find out how many spies of a certain type exist on a given channel, and are in state running.
 281   \param chan The channel on which to find the spies
 282   \param source The source of the audiohook
 283   \param type The type of spy to look for
 284   \return Return the number of running audiohooks which are from the source specified
 285
 286   Note: Function performs no locking.
 287 */
 288 int ast_channel_audiohook_count_by_source_running(struct ast_channel *chan, const char *source, enum ast_audiohook_type type);
 289
 290 /*! \brief Lock an audiohook
 291  * \param ah Audiohook structure
 292  */
 293 #define ast_audiohook_lock(ah) ast_mutex_lock(&(ah)->lock)
 294
 295 /*! \brief Unlock an audiohook
 296  * \param ah Audiohook structure
 297  */
 298 #define ast_audiohook_unlock(ah) ast_mutex_unlock(&(ah)->lock)
 299
 300 /*!
 301  * \brief Adjust the volume on frames read from or written to a channel
 302  * \param chan Channel to muck with
 303  * \param direction Direction to set on
 304  * \param volume Value to adjust the volume by
 305  * \return Returns 0 on success, -1 on failure
 306  * \since 1.6.1
 307  */
 308 int ast_audiohook_volume_set(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
 309
 310 /*!
 311  * \brief Retrieve the volume adjustment value on frames read from or written to a channel
 312  * \param chan Channel to retrieve volume adjustment from
 313  * \param direction Direction to retrieve
 314  * \return Returns adjustment value
 315  * \since 1.6.1
 316  */
 317 int ast_audiohook_volume_get(struct ast_channel *chan, enum ast_audiohook_direction direction);
 318
 319 /*!
 320  * \brief Adjust the volume on frames read from or written to a channel
 321  * \param chan Channel to muck with
 322  * \param direction Direction to increase
 323  * \param volume Value to adjust the adjustment by
 324  * \return Returns 0 on success, -1 on failure
 325  * \since 1.6.1
 326  */
 327 int ast_audiohook_volume_adjust(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
 328
 329 /*! \brief Mute frames read from or written to a channel
 330  * \param chan Channel to muck with
 331  * \param source Type of audiohook
 332  * \param flag which direction to set / clear
 333  * \param clear set or clear muted frames on direction based on flag parameter
 334  * \retval 0 success
 335  * \retval -1 failure
 336  */
 337 int ast_audiohook_set_mute(struct ast_channel *chan, const char *source, enum ast_audiohook_flags flag, int clear);
 338
 339 #if defined(__cplusplus) || defined(c_plusplus)
 340 }
 341 #endif
 342
 343 #endif /* _ASTERISK_AUDIOHOOK_H */