Wed Jan 8 2020 09:49:48

Asterisk developer's documentation


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