Asterisk - The Open Source Telephony Project  GIT-master-1f78ee9
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  */
74 struct ast_tone_zone {
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  */
127 int 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  */
136 struct ast_tone_zone *ast_get_indication_zone(const char *country);
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  */
146 struct 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  */
159 int 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  */
166 void 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  */
173 int 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  */
205 static 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  */
216 static 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 */
Main Channel structure associated with a channel.
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
A description of a part of a tone.
Definition: indications.h:109
unsigned int midinote
Definition: indications.h:114
void ast_playtones_stop(struct ast_channel *chan)
Stop playing tones on a channel.
Definition: indications.c:393
#define NULL
Definition: resample.c:96
unsigned int freq1
Definition: indications.h:110
Utility functions.
A set of tones for a given locale.
Definition: indications.h:74
int ast_tone_zone_count(void)
Get the number of registered tone zones.
Definition: indications.c:398
#define ao2_ref(o, delta)
Definition: astobj2.h:464
#define MAX_TONEZONE_COUNTRY
Definition: indications.h:64
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
struct ast_tone_zone_sound::@258 entry
Linked list fields for including in the list on an ast_tone_zone.
AST_LIST_HEAD_NOLOCK(contactliststruct, contact)
const char * name
Name of the tone. For example, "busy".
Definition: indications.h:37
unsigned int time
Definition: indications.h:112
static char country[80]
Definition: pbx_dundi.c:205
static char * tz
Definition: cdr_pgsql.c:75
struct ast_tone_zone * ast_get_indication_zone(const char *country)
locate ast_tone_zone
Definition: indications.c:433
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
Description of a tone.
Definition: indications.h:35
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:455
unsigned int killme
Definition: indications.h:98
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
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
unsigned int killme
Definition: indications.h:59
int * ringcadence
Array of ring cadence parts.
Definition: indications.h:91
unsigned int modulate
Definition: indications.h:113
When we need to walk through a container, we use an ao2_iterator to keep track of the current positio...
Definition: astobj2.h:1841
unsigned int nrringcadence
Number of ring cadence elements in the ringcadence array.
Definition: indications.h:84
struct ao2_iterator ast_tone_zone_iterator_init(void)
Get an iterator for the available tone zones.
Definition: indications.c:403
unsigned int freq2
Definition: indications.h:111
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
const char * data
Description of a tone.
Definition: indications.h:52
uint32_t __padding
Definition: indications.h:96
int ast_tone_zone_part_parse(const char *s, struct ast_tone_zone_part *tone_data)
Parse a tone part.
Definition: indications.c:245