Asterisk - The Open Source Telephony Project GIT-master-67613d1
indications.h
Go to the documentation of this file.
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
32/*!
33 * \brief Description of a tone
34 */
36 /*! \brief Name of the tone. For example, "busy". */
37 const char *name;
38 /*!
39 * \brief Description of a tone
40 *
41 * The format is a comma separated list of tone parts in the following format:
42 *
43 * Format: [!][M]freq[<+|*>freq2][/duration]
44 * - '!' - means that the element is NOT repeated
45 * - 'M' - interpret the frequencies as midi notes instead of frequencies
46 * - freq - The first frequency
47 * - freq2 - The second frequency (optional)
48 * - '*' - modulate freq by freq2 at a fixed depth of 90%
49 * - '+' - combine the frequencies
50 * - duration - the length of the tone part (optional, forever if not specified)
51 */
52 const char *data;
53 /*! \brief Linked list fields for including in the list on an ast_tone_zone */
55 /*! \brief Flags only used internally */
56 union {
57 uint32_t __padding;
58 struct {
59 unsigned int killme:1;
60 };
61 };
62};
63
64#define MAX_TONEZONE_COUNTRY 16
65
66/*!
67 * \brief A set of tones for a given locale
68 *
69 * \note If a reference to this tone zone is held, then the country
70 * is guaranteed not to change. It is safe to read it without
71 * locking the tone zone. This is not the case for any other
72 * field.
73 */
75 /*! \brief Country code that this set of tones is for */
77 /*!
78 * \brief Text description of the given country.
79 *
80 * This is for nothing more than friendly display to a human.
81 */
82 char description[40];
83 /*! \brief Number of ring cadence elements in the ringcadence array */
84 unsigned int nrringcadence;
85 /*!
86 * \brief Array of ring cadence parts
87 *
88 * Each element is an amount of time in milliseconds. The first element
89 * is for time on, and from there it alternates between on and off.
90 */
92 /*! \brief A list of tones for this locale */
94 /*! \brief Flags only used internally */
95 union {
96 uint32_t __padding;
97 struct {
98 unsigned int killme:1;
99 };
100 };
101};
102
103/*!
104 * \brief A description of a part of a tone
105 *
106 * The elements in this structure map to the format described for the data
107 * part of the ast_tone_zone_sound struct.
108 */
110 unsigned int freq1;
111 unsigned int freq2;
112 unsigned int time;
113 unsigned int modulate:1;
114 unsigned int midinote:1;
115};
116
117/*!
118 * \brief Parse a tone part
119 *
120 * \param s The part of a tone to parse. This should be in the form described for
121 * the data part of ast_tone_zone_sound. '!' should be removed if present.
122 * \param tone_data An output parameter that contains the result of the parsing.
123 *
124 * \retval 0 success
125 * \retval -1 failure, and the contents of tone_data are undefined
126 */
127int ast_tone_zone_part_parse(const char *s, struct ast_tone_zone_part *tone_data);
128
129/*!
130 * \brief locate ast_tone_zone
131 *
132 * \param country country to find. If NULL is provided, get the default.
133 *
134 * \return a reference to the specified country if found or NULL if not found
135 */
137
138/*!
139 * \brief Locate a tone zone sound
140 *
141 * \param zone Zone to look in for a sound, if NULL, the default will be used
142 * \param indication Sound to look for, such as "busy"
143 *
144 * \return a reference to the specified sound if it exists, NULL if not
145 */
146struct ast_tone_zone_sound *ast_get_indication_tone(const struct ast_tone_zone *zone, const char *indication);
147
148/*!
149 * \brief Start playing a list of tones on a channel
150 *
151 * \param chan the channel to play tones on
152 * \param vol volume
153 * \param tonelist the list of tones to play, comma separated
154 * \param interruptible whether or not this tone can be interrupted
155 *
156 * \retval 0 success
157 * \retval non-zero failure
158 */
159int ast_playtones_start(struct ast_channel *chan, int vol, const char *tonelist, int interruptible);
160
161/*!
162 * \brief Stop playing tones on a channel
163 *
164 * \param chan the channel to stop tones on
165 */
166void ast_playtones_stop(struct ast_channel *chan);
167
168/*!
169 * \brief Get the number of registered tone zones
170 *
171 * \return the total number of registered tone zones
172 */
173int ast_tone_zone_count(void);
174
175/*!
176 * \brief Get an iterator for the available tone zones
177 *
178 * \note Use ao2_iterator_next() to iterate the tone zones.
179 * \note Use ao2_iterator_destroy() to clean up.
180 *
181 * \return an initialized iterator
182 */
184
185/*!
186 * \brief Lock an ast_tone_zone
187 */
188#define ast_tone_zone_lock(tz) ao2_lock(tz)
189
190/*!
191 * \brief Unlock an ast_tone_zone
192 */
193#define ast_tone_zone_unlock(tz) ao2_unlock(tz)
194
195/*!
196 * \brief Trylock an ast_tone_zone
197 */
198#define ast_tone_zone_trylock(tz) ao2_trylock(tz)
199
200/*!
201 * \brief Release a reference to an ast_tone_zone
202 *
203 * \return NULL
204 */
205static inline struct ast_tone_zone *ast_tone_zone_unref(struct ast_tone_zone *tz)
206{
207 ao2_ref(tz, -1);
208 return NULL;
209}
210
211/*!
212 * \brief Increase the reference count on an ast_tone_zone
213 *
214 * \return The tone zone provided as an argument
215 */
216static inline struct ast_tone_zone *ast_tone_zone_ref(struct ast_tone_zone *tz)
217{
218 ao2_ref(tz, +1);
219 return tz;
220}
221
222/*!
223 * \brief Release a reference to an ast_tone_zone_sound
224 *
225 * \return NULL
226 */
228{
229 ao2_ref(ts, -1);
230 return NULL;
231}
232
233/*!
234 * \brief Increase the reference count on an ast_tone_zone_sound
235 *
236 * \return The tone zone sound provided as an argument
237 */
239{
240 ao2_ref(ts, +1);
241 return ts;
242}
243
244#endif /* _ASTERISK_INDICATIONS_H */
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
static char * tz
Definition: cdr_pgsql.c:71
static struct ast_tone_zone_sound * ast_tone_zone_sound_unref(struct ast_tone_zone_sound *ts)
Release a reference to an ast_tone_zone_sound.
Definition: indications.h:227
#define MAX_TONEZONE_COUNTRY
Definition: indications.h:64
int ast_playtones_start(struct ast_channel *chan, int vol, const char *tonelist, int interruptible)
Start playing a list of tones on a channel.
Definition: indications.c:302
int ast_tone_zone_part_parse(const char *s, struct ast_tone_zone_part *tone_data)
Parse a tone part.
Definition: indications.c:245
struct ao2_iterator ast_tone_zone_iterator_init(void)
Get an iterator for the available tone zones.
Definition: indications.c:403
void ast_playtones_stop(struct ast_channel *chan)
Stop playing tones on a channel.
Definition: indications.c:393
struct ast_tone_zone_sound * ast_get_indication_tone(const struct ast_tone_zone *zone, const char *indication)
Locate a tone zone sound.
Definition: indications.c:461
static struct ast_tone_zone * ast_tone_zone_unref(struct ast_tone_zone *tz)
Release a reference to an ast_tone_zone.
Definition: indications.h:205
struct ast_tone_zone * ast_get_indication_zone(const char *country)
locate ast_tone_zone
Definition: indications.c:439
static struct ast_tone_zone_sound * ast_tone_zone_sound_ref(struct ast_tone_zone_sound *ts)
Increase the reference count on an ast_tone_zone_sound.
Definition: indications.h:238
static struct ast_tone_zone * ast_tone_zone_ref(struct ast_tone_zone *tz)
Increase the reference count on an ast_tone_zone.
Definition: indications.h:216
int ast_tone_zone_count(void)
Get the number of registered tone zones.
Definition: indications.c:398
#define AST_LIST_HEAD_NOLOCK(name, type)
Defines a structure to be used to hold a list of specified type (with no lock).
Definition: linkedlists.h:225
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
static char country[80]
Definition: pbx_dundi.c:205
#define NULL
Definition: resample.c:96
When we need to walk through a container, we use an ao2_iterator to keep track of the current positio...
Definition: astobj2.h:1821
Main Channel structure associated with a channel.
A description of a part of a tone.
Definition: indications.h:109
unsigned int modulate
Definition: indications.h:113
unsigned int freq2
Definition: indications.h:111
unsigned int time
Definition: indications.h:112
unsigned int midinote
Definition: indications.h:114
unsigned int freq1
Definition: indications.h:110
Description of a tone.
Definition: indications.h:35
unsigned int killme
Definition: indications.h:59
const char * data
Description of a tone.
Definition: indications.h:52
const char * name
Name of the tone. For example, "busy".
Definition: indications.h:37
struct ast_tone_zone_sound::@229 entry
Linked list fields for including in the list on an ast_tone_zone.
A set of tones for a given locale.
Definition: indications.h:74
unsigned int killme
Definition: indications.h:98
unsigned int nrringcadence
Number of ring cadence elements in the ringcadence array.
Definition: indications.h:84
char description[40]
Text description of the given country.
Definition: indications.h:82
struct ast_tone_zone::@234 tones
A list of tones for this locale.
char country[MAX_TONEZONE_COUNTRY]
Country code that this set of tones is for.
Definition: indications.h:76
uint32_t __padding
Definition: indications.h:96
int * ringcadence
Array of ring cadence parts.
Definition: indications.h:91
Utility functions.