2 * Asterisk -- An open source telephony toolkit.
4 * Copyright (C) 1999 - 2007, Digium, Inc.
6 * Joshua Colp <jcolp@digium.com>
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.
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.
20 * \brief Audiohooks Architecture
23 #ifndef _ASTERISK_AUDIOHOOK_H
24 #define _ASTERISK_AUDIOHOOK_H
26 #if defined(__cplusplus) || defined(c_plusplus)
30 /* these two are used in struct ast_audiohook */
31 #include "asterisk/lock.h"
32 #include "asterisk/linkedlists.h"
34 #include "asterisk/slinfactory.h"
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 */
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 */
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 */
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 */
64 /*! \brief Callback function for manipulate audiohook type
65 * \param audiohook Audiohook structure
67 * \param frame Frame of audio to manipulate
68 * \param direction Direction frame came from
69 * \return Returns 0 on success, -1 on failure
70 * \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
71 * via it's own method. An example would be datastores.
73 typedef int (*ast_audiohook_manipulate_callback)(struct ast_audiohook *audiohook, struct ast_channel *chan, struct ast_frame *frame, enum ast_audiohook_direction direction);
75 struct ast_audiohook_options {
76 int read_volume; /*!< Volume adjustment on frames read from the channel the hook is on */
77 int write_volume; /*!< Volume adjustment on frames written to the channel the hook is on */
80 struct ast_audiohook {
81 ast_mutex_t lock; /*!< Lock that protects the audiohook structure */
82 ast_cond_t trigger; /*!< Trigger condition (if enabled) */
83 enum ast_audiohook_type type; /*!< Type of audiohook */
84 enum ast_audiohook_status status; /*!< Status of the audiohook */
85 const char *source; /*!< Who this audiohook ultimately belongs to */
86 unsigned int flags; /*!< Flags on the audiohook */
87 struct ast_slinfactory read_factory; /*!< Factory where frames read from the channel, or read from the whisper source will go through */
88 struct ast_slinfactory write_factory; /*!< Factory where frames written to the channel will go through */
89 int format; /*!< Format translation path is setup as */
90 struct ast_trans_pvt *trans_pvt; /*!< Translation path for reading frames */
91 ast_audiohook_manipulate_callback manipulate_callback; /*!< Manipulation callback */
92 struct ast_audiohook_options options; /*!< Applicable options */
93 AST_LIST_ENTRY(ast_audiohook) list; /*!< Linked list information */
96 struct ast_audiohook_list;
98 /*! \brief Initialize an audiohook structure
99 * \param audiohook Audiohook structure
100 * \param type Type of audiohook to initialize this as
101 * \param source Who is initializing this audiohook
102 * \return Returns 0 on success, -1 on failure
104 int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source);
106 /*! \brief Destroys an audiohook structure
107 * \param audiohook Audiohook structure
108 * \return Returns 0 on success, -1 on failure
110 int ast_audiohook_destroy(struct ast_audiohook *audiohook);
112 /*! \brief Writes a frame into the audiohook structure
113 * \param audiohook Audiohook structure
114 * \param direction Direction the audio frame came from
115 * \param frame Frame to write in
116 * \return Returns 0 on success, -1 on failure
118 int ast_audiohook_write_frame(struct ast_audiohook *audiohook, enum ast_audiohook_direction direction, struct ast_frame *frame);
120 /*! \brief Reads a frame in from the audiohook structure
121 * \param audiohook Audiohook structure
122 * \param samples Number of samples wanted
123 * \param direction Direction the audio frame came from
124 * \param format Format of frame remote side wants back
125 * \return Returns frame on success, NULL on failure
127 struct ast_frame *ast_audiohook_read_frame(struct ast_audiohook *audiohook, size_t samples, enum ast_audiohook_direction direction, int format);
129 /*! \brief Attach audiohook to channel
130 * \param chan Channel
131 * \param audiohook Audiohook structure
132 * \return Returns 0 on success, -1 on failure
134 int ast_audiohook_attach(struct ast_channel *chan, struct ast_audiohook *audiohook);
136 /*! \brief Detach audiohook from channel
137 * \param audiohook Audiohook structure
138 * \return Returns 0 on success, -1 on failure
140 int ast_audiohook_detach(struct ast_audiohook *audiohook);
142 /*! \brief Detach audiohooks from list and destroy said list
143 * \param audiohook_list List of audiohooks
144 * \return Returns 0 on success, -1 on failure
146 int ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list);
149 * \brief Detach specified source audiohook from channel
151 * \param chan Channel to detach from
152 * \param source Name of source to detach
154 * \return Returns 0 on success, -1 on failure
156 * \note The channel does not need to be locked before calling this function.
158 int ast_audiohook_detach_source(struct ast_channel *chan, const char *source);
160 /*! \brief Pass a frame off to be handled by the audiohook core
161 * \param chan Channel that the list is coming off of
162 * \param audiohook_list List of audiohooks
163 * \param direction Direction frame is coming in from
164 * \param frame The frame itself
165 * \return Return frame on success, NULL on failure
167 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);
169 /*! \brief Wait for audiohook trigger to be triggered
170 * \param audiohook Audiohook to wait on
172 void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook);
174 /*! \brief Lock an audiohook
175 * \param ah Audiohook structure
177 #define ast_audiohook_lock(ah) ast_mutex_lock(&(ah)->lock)
179 /*! \brief Unlock an audiohook
180 * \param ah Audiohook structure
182 #define ast_audiohook_unlock(ah) ast_mutex_unlock(&(ah)->lock)
184 #if defined(__cplusplus) || defined(c_plusplus)
188 #endif /* _ASTERISK_AUDIOHOOK_H */