Audit of ao2_iterator_init() usage for v1.8.
[asterisk/asterisk.git] / include / asterisk / indications.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2002, Pauline Middelink
5  * Copyright (C) 2009, Digium, Inc.
6  *
7  * See http://www.asterisk.org for more information about
8  * the Asterisk project. Please do not directly contact
9  * any of the maintainers of this project for assistance;
10  * the project provides a web site, mailing lists and IRC
11  * channels for your use.
12  *
13  * This program is free software, distributed under the terms of
14  * the GNU General Public License Version 2. See the LICENSE file
15  * at the top of the source tree.
16  */
17
18 /*!
19  * \file
20  * \brief Tone Indication Support
21  *
22  * \author Pauline Middelink <middelink@polyware.nl>
23  * \author Russell Bryant <russell@digium.com>
24  */
25
26 #ifndef _ASTERISK_INDICATIONS_H
27 #define _ASTERISK_INDICATIONS_H
28
29 #include "asterisk/astobj2.h"
30 #include "asterisk/utils.h"
31 #include "asterisk/data.h"
32
33 /*!
34  * \brief Description of a tone
35  */
36 struct ast_tone_zone_sound {
37         /*! \brief Name of the tone.  For example, "busy". */
38         const char *name;
39         /*!
40          * \brief Description of a tone
41          *
42          * The format is a comma separated list of tone parts in the following format:
43          *
44          * Format: [!][M]freq[<+|*>freq2][/duration]
45          *  - '!' - means that the element is NOT repeated
46          *  - 'M' - interpret the frequencies as midi notes instead of frequencies
47          *  - freq - The first frequency
48          *  - freq2 - The second frequency (optional)
49          *  - '*' - modulate freq by freq2 at a fixed depth of 90%
50          *  - '+' - combine the frequencies
51          *  - duration - the length of the tone part (optional, forever if not specified)
52          */
53         const char *data;
54         /*! \brief Linked list fields for including in the list on an ast_tone_zone */
55         AST_LIST_ENTRY(ast_tone_zone_sound) entry;
56         /*! \brief Flags only used internally */
57         union {
58                 uint32_t __padding;
59                 struct {
60                         unsigned int killme:1;
61                 };
62         };
63 };
64
65 #define MAX_TONEZONE_COUNTRY 16
66
67 /*!
68  * \brief A set of tones for a given locale
69  *
70  * \note If a reference to this tone zone is held, then the country
71  *       is guaranteed not to change.  It is safe to read it without
72  *       locking the tone zone.  This is not the case for any other
73  *       field.
74  */
75 struct ast_tone_zone {
76         /*! \brief Country code that this set of tones is for */
77         char country[MAX_TONEZONE_COUNTRY];
78         /*! 
79          * \brief Text description of the given country.
80          *
81          * This is for nothing more than friendly display to a human.
82          */
83         char description[40];
84         /*! \brief Number of ring cadence elements in the ringcadence array */
85         unsigned int  nrringcadence;
86         /*! 
87          * \brief Array of ring cadence parts
88          *
89          * Each element is an amount of time in milliseconds.  The first element
90          * is for time on, and from there it alternates between on and off.
91          */
92         int *ringcadence;
93         /*! \brief A list of tones for this locale */
94         AST_LIST_HEAD_NOLOCK(, ast_tone_zone_sound) tones;
95         /*! \brief Flags only used internally */
96         union {
97                 uint32_t __padding;
98                 struct {
99                         unsigned int killme:1;
100                 };
101         };
102 };
103
104 /*!
105  * \brief A description of a part of a tone
106  *
107  * The elements in this structure map to the format described for the data
108  * part of the ast_tone_zone_sound struct.
109  */
110 struct ast_tone_zone_part {
111         unsigned int freq1;
112         unsigned int freq2;
113         unsigned int time;
114         unsigned int modulate:1;
115         unsigned int midinote:1;
116 };
117
118 /*!
119  * \brief Parse a tone part
120  *
121  * \param s The part of a tone to parse.  This should be in the form described for
122  *        the data part of ast_tone_zone_sound.  '!' should be removed if present.
123  * \param tone_data An output parameter that contains the result of the parsing.
124  *
125  * \retval 0 success
126  * \retval -1 failure, and the contents of tone_data are undefined
127  */
128 int ast_tone_zone_part_parse(const char *s, struct ast_tone_zone_part *tone_data);
129
130 /*!
131  * \brief locate ast_tone_zone
132  *
133  * \param country country to find.  If NULL is provided, get the default.
134  *
135  * \return a reference to the specified country if found or NULL if not found
136  */
137 struct ast_tone_zone *ast_get_indication_zone(const char *country);
138
139 /*!
140  * \brief Locate a tone zone sound
141  *
142  * \param zone Zone to look in for a sound, if NULL, the default will be used
143  * \param indication Sound to look for, such as "busy"
144  *
145  * \return a reference to the specified sound if it exists, NULL if not
146  */
147 struct ast_tone_zone_sound *ast_get_indication_tone(const struct ast_tone_zone *zone, const char *indication);
148
149 /*!
150  * \brief Start playing a list of tones on a channel
151  *
152  * \param chan the channel to play tones on
153  * \param vol volume
154  * \param tonelist the list of tones to play, comma separated
155  * \param interruptible whether or not this tone can be interrupted
156  *
157  * \retval 0 success
158  * \retval non-zero failure
159  */
160 int ast_playtones_start(struct ast_channel *chan, int vol, const char *tonelist, int interruptible);
161
162 /*!
163  * \brief Stop playing tones on a channel
164  *
165  * \param chan the channel to stop tones on
166  */
167 void ast_playtones_stop(struct ast_channel *chan);
168
169 /*!
170  * \brief Get the number of registered tone zones
171  *
172  * \return the total number of registered tone zones
173  */
174 int ast_tone_zone_count(void);
175
176 /*!
177  * \brief Get an iterator for the available tone zones
178  *
179  * \note Use ao2_iterator_next() to iterate the tone zones.
180  * \note Use ao2_iterator_destroy() to clean up.
181  *
182  * \return an initialized iterator
183  */
184 struct ao2_iterator ast_tone_zone_iterator_init(void);
185
186 /*!
187  * \brief Lock an ast_tone_zone
188  */
189 #define ast_tone_zone_lock(tz) ao2_lock(tz)
190
191 /*!
192  * \brief Unlock an ast_tone_zone
193  */
194 #define ast_tone_zone_unlock(tz) ao2_unlock(tz)
195
196 /*!
197  * \brief Trylock an ast_tone_zone
198  */
199 #define ast_tone_zone_trylock(tz) ao2_trylock(tz)
200
201 /*!
202  * \brief Release a reference to an ast_tone_zone
203  *
204  * \return NULL
205  */
206 static inline struct ast_tone_zone *ast_tone_zone_unref(struct ast_tone_zone *tz)
207 {
208         ao2_ref(tz, -1);
209         return NULL;
210 }
211
212 /*!
213  * \brief Increase the reference count on an ast_tone_zone
214  *
215  * \return The tone zone provided as an argument
216  */
217 static inline struct ast_tone_zone *ast_tone_zone_ref(struct ast_tone_zone *tz)
218 {
219         ao2_ref(tz, +1);
220         return tz;
221 }
222
223 /*!
224  * \brief Release a reference to an ast_tone_zone_sound
225  *
226  * \return NULL
227  */
228 static inline struct ast_tone_zone_sound *ast_tone_zone_sound_unref(struct ast_tone_zone_sound *ts)
229 {
230         ao2_ref(ts, -1);
231         return NULL;
232 }
233
234 /*!
235  * \brief Increase the reference count on an ast_tone_zone_sound
236  *
237  * \return The tone zone sound provided as an argument
238  */
239 static inline struct ast_tone_zone_sound *ast_tone_zone_sound_ref(struct ast_tone_zone_sound *ts)
240 {
241         ao2_ref(ts, +1);
242         return ts;
243 }
244
245 /*!
246  * \brief Add a tone_zone structure to the data tree specified.
247  *
248  * \retval <0 on error.
249  * \retval 0 on success.
250  */
251 int ast_tone_zone_data_add_structure(struct ast_data *tree, struct ast_tone_zone *zone);
252
253 #endif /* _ASTERISK_INDICATIONS_H */