From 602198c402ebf5d6b2fd82149b1377146c6b8814 Mon Sep 17 00:00:00 2001 From: Joshua Colp Date: Wed, 8 Aug 2007 19:30:52 +0000 Subject: Merge audiohooks branch into trunk. This is a new API for developers to listen and manipulate the audio going through a channel. git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@78649 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- include/asterisk/audiohook.h | 185 +++++++++++++++++++++++++++++++++++++++++ include/asterisk/channel.h | 7 +- include/asterisk/chanspy.h | 150 --------------------------------- include/asterisk/slinfactory.h | 1 + 4 files changed, 188 insertions(+), 155 deletions(-) create mode 100644 include/asterisk/audiohook.h delete mode 100644 include/asterisk/chanspy.h (limited to 'include') diff --git a/include/asterisk/audiohook.h b/include/asterisk/audiohook.h new file mode 100644 index 000000000..a374a630a --- /dev/null +++ b/include/asterisk/audiohook.h @@ -0,0 +1,185 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 1999 - 2007, Digium, Inc. + * + * Joshua Colp + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +/*! \file + * \brief Audiohooks Architecture + */ + +#ifndef _ASTERISK_AUDIOHOOK_H +#define _ASTERISK_AUDIOHOOK_H + +#if defined(__cplusplus) || defined(c_plusplus) +extern "C" { +#endif + +#include "asterisk/slinfactory.h" + +enum ast_audiohook_type { + AST_AUDIOHOOK_TYPE_SPY = 0, /*!< Audiohook wants to receive audio */ + AST_AUDIOHOOK_TYPE_WHISPER, /*!< Audiohook wants to provide audio to be mixed with existing audio */ + AST_AUDIOHOOK_TYPE_MANIPULATE, /*!< Audiohook wants to manipulate the audio */ +}; + +enum ast_audiohook_status { + AST_AUDIOHOOK_STATUS_NEW = 0, /*!< Audiohook was just created, not in use yet */ + AST_AUDIOHOOK_STATUS_RUNNING, /*!< Audiohook is running on a channel */ + AST_AUDIOHOOK_STATUS_SHUTDOWN, /*!< Audiohook is being shutdown */ + AST_AUDIOHOOK_STATUS_DONE, /*!< Audiohook has shutdown and is not running on a channel any longer */ +}; + +enum ast_audiohook_direction { + AST_AUDIOHOOK_DIRECTION_READ = 0, /*!< Reading audio in */ + AST_AUDIOHOOK_DIRECTION_WRITE, /*!< Writing audio out */ + AST_AUDIOHOOK_DIRECTION_BOTH, /*!< Both reading audio in and writing audio out */ +}; + +enum ast_audiohook_flags { + AST_AUDIOHOOK_TRIGGER_MODE = (3 << 0), /*!< When audiohook should be triggered to do something */ + AST_AUDIOHOOK_TRIGGER_READ = (1 << 0), /*!< Audiohook wants to be triggered when reading audio in */ + AST_AUDIOHOOK_TRIGGER_WRITE = (2 << 0), /*!< Audiohook wants to be triggered when writing audio out */ + AST_AUDIOHOOK_WANTS_DTMF = (1 << 1), /*!< Audiohook also wants to receive DTMF frames */ +}; + +struct ast_audiohook; + +/*! \brief Callback function for manipulate audiohook type + * \param audiohook Audiohook structure + * \param chan Channel + * \param frame Frame of audio to manipulate + * \param direction Direction frame came from + * \return Returns 0 on success, -1 on failure + * \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 + * via it's own method. An example would be datastores. + */ +typedef int (*ast_audiohook_manipulate_callback)(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction); + +struct ast_audiohook_options { + int read_volume; /*!< Volume adjustment on frames read from the channel the hook is on */ + int write_volume; /*!< Volume adjustment on frames written to the channel the hook is on */ +}; + +struct ast_audiohook { + ast_mutex_t lock; /*!< Lock that protects the audiohook structure */ + ast_cond_t trigger; /*!< Trigger condition (if enabled) */ + enum ast_audiohook_type type; /*!< Type of audiohook */ + enum ast_audiohook_status status; /*!< Status of the audiohook */ + const char *source; /*!< Who this audiohook ultimately belongs to */ + unsigned int flags; /*!< Flags on the audiohook */ + struct ast_slinfactory read_factory; /*!< Factory where frames read from the channel, or read from the whisper source will go through */ + struct ast_slinfactory write_factory; /*!< Factory where frames written to the channel will go through */ + int format; /*!< Format translation path is setup as */ + struct ast_trans_pvt *trans_pvt; /*!< Translation path for reading frames */ + ast_audiohook_manipulate_callback manipulate_callback; /*!< Manipulation callback */ + struct ast_audiohook_options options; /*!< Applicable options */ + AST_LIST_ENTRY(ast_audiohook) list; /*!< Linked list information */ +}; + +struct ast_audiohook_list; + +/*! \brief Initialize an audiohook structure + * \param audiohook Audiohook structure + * \param type Type of audiohook to initialize this as + * \param source Who is initializing this audiohook + * \return Returns 0 on success, -1 on failure + */ +int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source); + +/*! \brief Destroys an audiohook structure + * \param audiohook Audiohook structure + * \return Returns 0 on success, -1 on failure + */ +int ast_audiohook_destroy(struct ast_audiohook *audiohook); + +/*! \brief Writes a frame into the audiohook structure + * \param audiohook Audiohook structure + * \param direction Direction the audio frame came from + * \param frame Frame to write in + * \return Returns 0 on success, -1 on failure + */ +int ast_audiohook_write_frame(struct ast_audiohook *audiohook, enum ast_audiohook_direction direction, struct ast_frame *frame); + +/*! \brief Reads a frame in from the audiohook structure + * \param audiohook Audiohook structure + * \param samples Number of samples wanted + * \param direction Direction the audio frame came from + * \param format Format of frame remote side wants back + * \return Returns frame on success, NULL on failure + */ +struct ast_frame *ast_audiohook_read_frame(struct ast_audiohook *audiohook, size_t samples, enum ast_audiohook_direction direction, int format); + +/*! \brief Attach audiohook to channel + * \param chan Channel + * \param audiohook Audiohook structure + * \return Returns 0 on success, -1 on failure + */ +int ast_audiohook_attach(struct ast_channel *chan, struct ast_audiohook *audiohook); + +/*! \brief Detach audiohook from channel + * \param audiohook Audiohook structure + * \return Returns 0 on success, -1 on failure + */ +int ast_audiohook_detach(struct ast_audiohook *audiohook); + +/*! \brief Detach audiohooks from list and destroy said list + * \param audiohook_list List of audiohooks + * \return Returns 0 on success, -1 on failure + */ +int ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list); + +/*! \brief Detach specified source audiohook from channel + * \param chan Channel to detach from + * \param source Name of source to detach + * \return Returns 0 on success, -1 on failure + */ +int ast_audiohook_detach_source(struct ast_channel *chan, const char *source); + +/*! \brief Pass a frame off to be handled by the audiohook core + * \param chan Channel that the list is coming off of + * \param audiohook_list List of audiohooks + * \param direction Direction frame is coming in from + * \param frame The frame itself + * \return Return frame on success, NULL on failure + */ +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); + +/*! \brief Wait for audiohook trigger to be triggered + * \param audiohook Audiohook to wait on + */ +void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook); + +/*! \brief Lock an audiohook + * \param audiohook Audiohook structure + */ +static inline int ast_audiohook_lock(struct ast_audiohook *audiohook) +{ + return ast_mutex_lock(&audiohook->lock); +} + +/*! \brief Unlock an audiohook + * \param audiohook Audiohook structure + */ +static inline int ast_audiohook_unlock(struct ast_audiohook *audiohook) +{ + return ast_mutex_unlock(&audiohook->lock); +} + +#if defined(__cplusplus) || defined(c_plusplus) +} +#endif + +#endif /* _ASTERISK_AUDIOHOOK_H */ diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h index 3e63259aa..39f2c636d 100644 --- a/include/asterisk/channel.h +++ b/include/asterisk/channel.h @@ -316,9 +316,6 @@ struct ast_channel_tech { int (* func_channel_write)(struct ast_channel *chan, const char *function, char *data, const char *value); }; -struct ast_channel_spy_list; /*!< \todo Add explanation here */ -struct ast_channel_whisper_buffer; /*!< \todo Add explanation here */ - /*! * The high bit of the frame count is used as a debug marker, so * increments of the counters must be done with care. @@ -481,8 +478,8 @@ struct ast_channel { int rawreadformat; /*!< Raw read format */ int rawwriteformat; /*!< Raw write format */ - struct ast_channel_spy_list *spies; /*!< Chan Spy stuff */ - struct ast_channel_whisper_buffer *whisper; /*!< Whisper Paging buffer */ + struct ast_audiohook_list *audiohooks; + AST_LIST_ENTRY(ast_channel) chan_list; /*!< For easy linking */ struct ast_jb jb; /*!< The jitterbuffer state */ diff --git a/include/asterisk/chanspy.h b/include/asterisk/chanspy.h deleted file mode 100644 index 8550210d0..000000000 --- a/include/asterisk/chanspy.h +++ /dev/null @@ -1,150 +0,0 @@ -/* - * Asterisk -- An open source telephony toolkit. - * - * Copyright (C) 1999 - 2006, Digium, Inc. - * - * Mark Spencer - * - * See http://www.asterisk.org for more information about - * the Asterisk project. Please do not directly contact - * any of the maintainers of this project for assistance; - * the project provides a web site, mailing lists and IRC - * channels for your use. - * - * This program is free software, distributed under the terms of - * the GNU General Public License Version 2. See the LICENSE file - * at the top of the source tree. - */ - -/*! \file - * \brief Asterisk PBX channel spy definitions - */ - -#ifndef _ASTERISK_CHANSPY_H -#define _ASTERISK_CHANSPY_H - -#if defined(__cplusplus) || defined(c_plusplus) -extern "C" { -#endif - -#include "asterisk/linkedlists.h" - -enum chanspy_states { - CHANSPY_NEW = 0, /*!< spy not yet operating */ - CHANSPY_RUNNING = 1, /*!< normal operation, spy is still operating */ - CHANSPY_DONE = 2, /*!< spy is stopped and already removed from channel */ - CHANSPY_STOP = 3, /*!< spy requested to stop, still attached to channel */ -}; - -enum chanspy_flags { - CHANSPY_MIXAUDIO = (1 << 0), - CHANSPY_READ_VOLADJUST = (1 << 1), - CHANSPY_WRITE_VOLADJUST = (1 << 2), - CHANSPY_FORMAT_AUDIO = (1 << 3), - CHANSPY_TRIGGER_MODE = (3 << 4), - CHANSPY_TRIGGER_READ = (1 << 4), - CHANSPY_TRIGGER_WRITE = (2 << 4), - CHANSPY_TRIGGER_NONE = (3 << 4), - CHANSPY_TRIGGER_FLUSH = (1 << 6), -}; - -struct ast_channel_spy_queue { - AST_LIST_HEAD_NOLOCK(, ast_frame) list; - unsigned int samples; - unsigned int format; -}; - -struct ast_channel_spy { - AST_LIST_ENTRY(ast_channel_spy) list; - ast_mutex_t lock; - ast_cond_t trigger; - struct ast_channel *chan; - struct ast_channel_spy_queue read_queue; - struct ast_channel_spy_queue write_queue; - unsigned int flags; - enum chanspy_states status; - const char *type; - /* The volume adjustment values are very straightforward: - positive values cause the samples to be multiplied by that amount - negative values cause the samples to be divided by the absolute value of that amount - */ - int read_vol_adjustment; - int write_vol_adjustment; -}; - -/*! - \brief Adds a spy to a channel, to begin receiving copies of the channel's audio frames. - \param chan The channel to add the spy to. - \param spy A pointer to ast_channel_spy structure describing how the spy is to be used. - \return 0 for success, non-zero for failure - - Note: This function performs no locking; you must hold the channel's lock before - calling this function. - */ -int ast_channel_spy_add(struct ast_channel *chan, struct ast_channel_spy *spy); - -/*! - \brief Remove a spy from a channel. - \param chan The channel to remove the spy from - \param spy The spy to be removed - \return nothing - - Note: This function performs no locking; you must hold the channel's lock before - calling this function. - */ -void ast_channel_spy_remove(struct ast_channel *chan, struct ast_channel_spy *spy); - -/*! - \brief Free a spy. - \param spy The spy to free - \return nothing - - Note: This function MUST NOT be called with the spy locked. -*/ -void ast_channel_spy_free(struct ast_channel_spy *spy); - -/*! - \brief Find all spies of a particular type on a channel and stop them. - \param chan The channel to operate on - \param type A character string identifying the type of spies to be stopped - \return nothing - - Note: This function performs no locking; you must hold the channel's lock before - calling this function. - */ -void ast_channel_spy_stop_by_type(struct ast_channel *chan, const char *type); - -/*! - \brief Read one (or more) frames of audio from a channel being spied upon. - \param spy The spy to operate on - \param samples The number of audio samples to read - \return NULL for failure, one ast_frame pointer, or a chain of ast_frame pointers - - This function can return multiple frames if the spy structure needs to be 'flushed' - due to mismatched queue lengths, or if the spy structure is configured to return - unmixed audio (in which case each call to this function will return a frame of audio - from each side of channel). - - Note: This function performs no locking; you must hold the spy's lock before calling - this function. You must not hold the channel's lock at the same time. - */ -struct ast_frame *ast_channel_spy_read_frame(struct ast_channel_spy *spy, unsigned int samples); - -/*! - \brief Efficiently wait until audio is available for a spy, or an exception occurs. - \param spy The spy to wait on - \return nothing - - Note: The locking rules for this function are non-obvious... first, you must not - hold the channel's lock when calling this function. Second, you must hold the spy's lock - before making the function call; while the function runs the lock will be released, and - when the trigger event occurs, the lock will be re-obtained. This means that when control - returns to your code, you will again hold the spy's lock. - */ -void ast_channel_spy_trigger_wait(struct ast_channel_spy *spy); - -#if defined(__cplusplus) || defined(c_plusplus) -} -#endif - -#endif /* _ASTERISK_CHANSPY_H */ diff --git a/include/asterisk/slinfactory.h b/include/asterisk/slinfactory.h index b81817d6b..3ab42d283 100644 --- a/include/asterisk/slinfactory.h +++ b/include/asterisk/slinfactory.h @@ -46,6 +46,7 @@ void ast_slinfactory_destroy(struct ast_slinfactory *sf); int ast_slinfactory_feed(struct ast_slinfactory *sf, struct ast_frame *f); int ast_slinfactory_read(struct ast_slinfactory *sf, short *buf, size_t samples); unsigned int ast_slinfactory_available(const struct ast_slinfactory *sf); +void ast_slinfactory_flush(struct ast_slinfactory *sf); #if defined(__cplusplus) || defined(c_plusplus) } -- cgit v1.2.3