Merged revisions 33724 via svnmerge from
[asterisk/asterisk.git] / include / asterisk / chanspy.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2006, Digium, Inc.
5  *
6  * Mark Spencer <markster@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 Asterisk PBX channel spy definitions
21  */
22
23 #ifndef _ASTERISK_CHANSPY_H
24 #define _ASTERISK_CHANSPY_H
25
26 #if defined(__cplusplus) || defined(c_plusplus)
27 extern "C" {
28 #endif
29
30 #include "asterisk/linkedlists.h"
31
32 enum chanspy_states {
33         CHANSPY_NEW = 0,                /*!< spy not yet operating */
34         CHANSPY_RUNNING = 1,            /*!< normal operation, spy is still operating */
35         CHANSPY_DONE = 2,               /*!< spy is stopped and already removed from channel */
36         CHANSPY_STOP = 3,               /*!< spy requested to stop, still attached to channel */
37 };
38
39 enum chanspy_flags {
40         CHANSPY_MIXAUDIO = (1 << 0),
41         CHANSPY_READ_VOLADJUST = (1 << 1),
42         CHANSPY_WRITE_VOLADJUST = (1 << 2),
43         CHANSPY_FORMAT_AUDIO = (1 << 3),
44         CHANSPY_TRIGGER_MODE = (3 << 4),
45         CHANSPY_TRIGGER_READ = (1 << 4),
46         CHANSPY_TRIGGER_WRITE = (2 << 4),
47         CHANSPY_TRIGGER_NONE = (3 << 4),
48         CHANSPY_TRIGGER_FLUSH = (1 << 6),
49 };
50
51 struct ast_channel_spy_queue {
52         struct ast_frame *head;
53         unsigned int samples;
54         unsigned int format;
55 };
56
57 struct ast_channel_spy {
58         AST_LIST_ENTRY(ast_channel_spy) list;
59         ast_mutex_t lock;
60         ast_cond_t trigger;
61         struct ast_channel *chan;
62         struct ast_channel_spy_queue read_queue;
63         struct ast_channel_spy_queue write_queue;
64         unsigned int flags;
65         enum chanspy_states status;
66         const char *type;
67         /* The volume adjustment values are very straightforward:
68            positive values cause the samples to be multiplied by that amount
69            negative values cause the samples to be divided by the absolute value of that amount
70         */
71         int read_vol_adjustment;
72         int write_vol_adjustment;
73 };
74
75 /*!
76   \brief Adds a spy to a channel, to begin receiving copies of the channel's audio frames.
77   \param chan The channel to add the spy to.
78   \param spy A pointer to ast_channel_spy structure describing how the spy is to be used.
79   \return 0 for success, non-zero for failure
80
81   Note: This function performs no locking; you must hold the channel's lock before
82   calling this function.
83  */
84 int ast_channel_spy_add(struct ast_channel *chan, struct ast_channel_spy *spy);
85
86 /*!
87   \brief Remove a spy from a channel.
88   \param chan The channel to remove the spy from
89   \param spy The spy to be removed
90   \return nothing
91
92   Note: This function performs no locking; you must hold the channel's lock before
93   calling this function.
94  */
95 void ast_channel_spy_remove(struct ast_channel *chan, struct ast_channel_spy *spy);
96
97 /*!
98   \brief Find all spies of a particular type on a channel and stop them.
99   \param chan The channel to operate on
100   \param type A character string identifying the type of spies to be stopped
101   \return nothing
102
103   Note: This function performs no locking; you must hold the channel's lock before
104   calling this function.
105  */
106 void ast_channel_spy_stop_by_type(struct ast_channel *chan, const char *type);
107
108 /*!
109   \brief Read one (or more) frames of audio from a channel being spied upon.
110   \param spy The spy to operate on
111   \param samples The number of audio samples to read
112   \return NULL for failure, one ast_frame pointer, or a chain of ast_frame pointers
113
114   This function can return multiple frames if the spy structure needs to be 'flushed'
115   due to mismatched queue lengths, or if the spy structure is configured to return
116   unmixed audio (in which case each call to this function will return a frame of audio
117   from each side of channel).
118
119   Note: This function performs no locking; you must hold the spy's lock before calling
120   this function. You must <b>not</b> hold the channel's lock at the same time.
121  */
122 struct ast_frame *ast_channel_spy_read_frame(struct ast_channel_spy *spy, unsigned int samples);
123
124 /*!
125   \brief Efficiently wait until audio is available for a spy, or an exception occurs.
126   \param spy The spy to wait on
127   \return nothing
128
129   Note: The locking rules for this function are non-obvious... first, you must <b>not</b>
130   hold the channel's lock when calling this function. Second, you must hold the spy's lock
131   before making the function call; while the function runs the lock will be released, and
132   when the trigger event occurs, the lock will be re-obtained. This means that when control
133   returns to your code, you will again hold the spy's lock.
134  */
135 void ast_channel_spy_trigger_wait(struct ast_channel_spy *spy);
136
137 #if defined(__cplusplus) || defined(c_plusplus)
138 }
139 #endif
140
141 #endif /* _ASTERISK_CHANSPY_H */