Wed Jan 8 2020 09:50:13

Asterisk developer's documentation


indications.h File Reference

Tone Indication Support. More...

#include "asterisk/astobj2.h"
#include "asterisk/utils.h"
#include "asterisk/data.h"

Go to the source code of this file.

Data Structures

struct  ast_tone_zone
 A set of tones for a given locale. More...
 
struct  ast_tone_zone_part
 A description of a part of a tone. More...
 
struct  ast_tone_zone_sound
 Description of a tone. More...
 

Macros

#define ast_tone_zone_lock(tz)   ao2_lock(tz)
 Lock an ast_tone_zone. More...
 
#define ast_tone_zone_trylock(tz)   ao2_trylock(tz)
 Trylock an ast_tone_zone. More...
 
#define ast_tone_zone_unlock(tz)   ao2_unlock(tz)
 Unlock an ast_tone_zone. More...
 

Functions

struct ast_tone_zone_soundast_get_indication_tone (const struct ast_tone_zone *zone, const char *indication)
 Locate a tone zone sound. More...
 
struct ast_tone_zoneast_get_indication_zone (const char *country)
 locate ast_tone_zone More...
 
int ast_playtones_start (struct ast_channel *chan, int vol, const char *tonelist, int interruptible)
 Start playing a list of tones on a channel. More...
 
void ast_playtones_stop (struct ast_channel *chan)
 Stop playing tones on a channel. More...
 
int ast_tone_zone_count (void)
 Get the number of registered tone zones. More...
 
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. More...
 
struct ao2_iterator ast_tone_zone_iterator_init (void)
 Get an iterator for the available tone zones. More...
 
int ast_tone_zone_part_parse (const char *s, struct ast_tone_zone_part *tone_data)
 Parse a tone part. More...
 
static struct ast_tone_zoneast_tone_zone_ref (struct ast_tone_zone *tz)
 Increase the reference count on an ast_tone_zone. More...
 
static struct ast_tone_zone_soundast_tone_zone_sound_ref (struct ast_tone_zone_sound *ts)
 Increase the reference count on an ast_tone_zone_sound. More...
 
static struct ast_tone_zone_soundast_tone_zone_sound_unref (struct ast_tone_zone_sound *ts)
 Release a reference to an ast_tone_zone_sound. More...
 
static struct ast_tone_zoneast_tone_zone_unref (struct ast_tone_zone *tz)
 Release a reference to an ast_tone_zone. More...
 

Detailed Description

Tone Indication Support.

Author
Pauline Middelink midde.nosp@m.link.nosp@m.@poly.nosp@m.ware.nosp@m..nl
Russell Bryant russe.nosp@m.ll@d.nosp@m.igium.nosp@m..com

Definition in file indications.h.

Macro Definition Documentation

#define ast_tone_zone_trylock (   tz)    ao2_trylock(tz)

Trylock an ast_tone_zone.

Definition at line 197 of file indications.h.

Function Documentation

struct ast_tone_zone_sound* ast_get_indication_tone ( const struct ast_tone_zone zone,
const char *  indication 
)

Locate a tone zone sound.

Parameters
zoneZone to look in for a sound, if NULL, the default will be used
indicationSound to look for, such as "busy"
Returns
a reference to the specified sound if it exists, NULL if not

Definition at line 473 of file indications.c.

References ao2_lock, ao2_unlock, AST_LIST_TRAVERSE, ast_tone_zone_lock, ast_tone_zone_ref(), ast_tone_zone_sound_ref(), ast_tone_zone_unlock, ast_tone_zone_sound::name, and ast_tone_zone::tones.

Referenced by ast_app_dtget(), ast_indicate_data(), dial_handle_playtones(), dialtone_indicate(), handle_playtones(), in_band_indication(), pbx_builtin_waitexten(), play_dialtone(), read_exec(), readexten_exec(), and skinny_transfer().

474 {
475  struct ast_tone_zone_sound *ts = NULL;
476  /* _zone is const to the users of the API */
477  struct ast_tone_zone *zone = (struct ast_tone_zone *) _zone;
478 
479  /* If no zone is specified, use the default */
480  if (!zone) {
482  if (default_tone_zone) {
484  }
486 
487  if (!zone) {
488  return NULL;
489  }
490  }
491 
492  ast_tone_zone_lock(zone);
493 
494  /* Look through list of tones in the zone searching for the right one */
495  AST_LIST_TRAVERSE(&zone->tones, ts, entry) {
496  if (!strcasecmp(ts->name, indication)) {
497  /* Increase ref count for the reference we will return */
498  ts = ast_tone_zone_sound_ref(ts);
499  break;
500  }
501  }
502 
503  ast_tone_zone_unlock(zone);
504 
505  return ts;
506 }
static struct ast_tone_zone * default_tone_zone
Definition: indications.c:88
#define ast_tone_zone_unlock(tz)
Unlock an ast_tone_zone.
Definition: indications.h:192
static struct ao2_container * ast_tone_zones
Definition: indications.c:81
struct ast_tone_zone::@181 tones
A list of tones for this locale.
#define ao2_unlock(a)
Definition: astobj2.h:497
A set of tones for a given locale.
Definition: indications.h:73
#define ao2_lock(a)
Definition: astobj2.h:488
const char * name
Name of the tone. For example, "busy".
Definition: indications.h:38
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
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_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:490
#define ast_tone_zone_lock(tz)
Lock an ast_tone_zone.
Definition: indications.h:187
struct ast_tone_zone* ast_get_indication_zone ( const char *  country)

locate ast_tone_zone

Parameters
countrycountry to find. If NULL is provided, get the default.
Returns
a reference to the specified country if found or NULL if not found

Definition at line 451 of file indications.c.

References ao2_find, ao2_lock, ao2_unlock, ast_copy_string(), ast_strlen_zero(), ast_tone_zone_ref(), ast_tone_zone::country, ast_tone_zone::nrringcadence, OBJ_POINTER, and tz.

Referenced by ast_set_indication_country(), ast_var_indications(), build_device(), func_channel_write_real(), handle_cli_indication_add(), and handle_cli_indication_remove().

452 {
453  struct ast_tone_zone *tz = NULL;
454  struct ast_tone_zone zone_arg = {
455  .nrringcadence = 0,
456  };
457 
458  if (ast_strlen_zero(country)) {
460  if (default_tone_zone) {
462  }
464 
465  return tz;
466  }
467 
468  ast_copy_string(zone_arg.country, country, sizeof(zone_arg.country));
469 
470  return ao2_find(ast_tone_zones, &zone_arg, OBJ_POINTER);
471 }
static struct ast_tone_zone * default_tone_zone
Definition: indications.c:88
static struct ao2_container * ast_tone_zones
Definition: indications.c:81
#define ao2_unlock(a)
Definition: astobj2.h:497
static char * tz
Definition: cdr_pgsql.c:56
A set of tones for a given locale.
Definition: indications.h:73
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:63
#define ao2_lock(a)
Definition: astobj2.h:488
static char country[80]
Definition: pbx_dundi.c:196
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 ao2_find(arg1, arg2, arg3)
Definition: astobj2.h:964
char country[16]
Country code that this set of tones is for.
Definition: indications.h:75
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:223
unsigned int nrringcadence
Number of ring cadence elements in the ringcadence array.
Definition: indications.h:83
int ast_playtones_start ( struct ast_channel chan,
int  vol,
const char *  tonelist,
int  interruptible 
)

Start playing a list of tones on a channel.

Parameters
chanthe channel to play tones on
volvolume
tonelistthe list of tones to play, comma separated
interruptiblewhether or not this tone can be interrupted
Return values
0success
non-zerofailure

Definition at line 319 of file indications.c.

References ast_activate_generator(), ast_free, ast_log(), ast_realloc, ast_strdupa, ast_strip(), ast_strlen_zero(), ast_tone_zone_part_parse(), cos, playtones_item::duration, playtones_item::fac1, playtones_item::fac2, ast_tone_zone_part::freq1, ast_tone_zone_part::freq2, playtones_item::init_v2_1, playtones_item::init_v2_2, playtones_item::init_v3_1, playtones_item::init_v3_2, playtones_def::interruptible, playtones_def::items, LOG_ERROR, M_PI, ast_tone_zone_part::midinote, playtones_item::modulate, ast_tone_zone_part::modulate, playtones_def::nitems, playtones_def::reppos, strsep(), ast_tone_zone_part::time, and playtones_def::vol.

Referenced by ast_app_dtget(), ast_indicate_data(), ast_senddigit_begin(), dial_handle_playtones(), dialtone_indicate(), handle_playtones(), in_band_indication(), milliwatt_exec(), pbx_builtin_waitexten(), play_dialtone(), playtone(), read_exec(), readexten_exec(), receivefax_t38_init(), send_digit_to_chan(), sendfax_t38_init(), and skinny_transfer().

320 {
321  char *s, *data = ast_strdupa(playlst);
322  struct playtones_def d = { vol, -1, 0, 1, NULL };
323  char *stringp;
324  char *separator;
325  static const float sample_rate = 8000.0;
326  static const float max_sample_val = 32768.0;
327 
328  if (vol < 1) {
329  d.vol = 7219; /* Default to -8db */
330  }
331 
333 
334  stringp = data;
335 
336  /* check if the data is separated with '|' or with ',' by default */
337  if (strchr(stringp,'|')) {
338  separator = "|";
339  } else {
340  separator = ",";
341  }
342 
343  while ((s = strsep(&stringp, separator)) && !ast_strlen_zero(s)) {
344  struct playtones_item *new_items;
345  struct ast_tone_zone_part tone_data = {
346  .time = 0,
347  };
348 
349  s = ast_strip(s);
350  if (s[0]=='!') {
351  s++;
352  } else if (d.reppos == -1) {
353  d.reppos = d.nitems;
354  }
355 
356  if (ast_tone_zone_part_parse(s, &tone_data)) {
357  ast_log(LOG_ERROR, "Failed to parse tone part '%s'\n", s);
358  continue;
359  }
360 
361  if (tone_data.midinote) {
362  /* midi notes must be between 0 and 127 */
363 
364  if (tone_data.freq1 >= 0 && tone_data.freq1 <= 127) {
365  tone_data.freq1 = midi_tohz[tone_data.freq1];
366  } else {
367  tone_data.freq1 = 0;
368  }
369 
370  if (tone_data.freq2 >= 0 && tone_data.freq2 <= 127) {
371  tone_data.freq2 = midi_tohz[tone_data.freq2];
372  } else {
373  tone_data.freq2 = 0;
374  }
375  }
376 
377  new_items = ast_realloc(d.items, (d.nitems + 1) * sizeof(*d.items));
378  if (!new_items) {
379  ast_free(d.items);
380  return -1;
381  }
382  d.items = new_items;
383 
384  d.items[d.nitems].fac1 = 2.0 * cos(2.0 * M_PI * (tone_data.freq1 / sample_rate)) * max_sample_val;
385  d.items[d.nitems].init_v2_1 = sin(-4.0 * M_PI * (tone_data.freq1 / sample_rate)) * d.vol;
386  d.items[d.nitems].init_v3_1 = sin(-2.0 * M_PI * (tone_data.freq1 / sample_rate)) * d.vol;
387 
388  d.items[d.nitems].fac2 = 2.0 * cos(2.0 * M_PI * (tone_data.freq2 / sample_rate)) * max_sample_val;
389  d.items[d.nitems].init_v2_2 = sin(-4.0 * M_PI * (tone_data.freq2 / sample_rate)) * d.vol;
390  d.items[d.nitems].init_v3_2 = sin(-2.0 * M_PI * (tone_data.freq2 / sample_rate)) * d.vol;
391 
392  d.items[d.nitems].duration = tone_data.time;
393  d.items[d.nitems].modulate = tone_data.modulate;
394 
395  d.nitems++;
396  }
397 
398  if (!d.nitems) {
399  ast_log(LOG_ERROR, "No valid tone parts\n");
400  return -1;
401  }
402 
403  if (ast_activate_generator(chan, &playtones, &d)) {
404  ast_free(d.items);
405  return -1;
406  }
407 
408  return 0;
409 }
char * strsep(char **str, const char *delims)
int ast_activate_generator(struct ast_channel *chan, struct ast_generator *gen, void *params)
Definition: channel.c:3148
A description of a part of a tone.
Definition: indications.h:108
unsigned int midinote
Definition: indications.h:113
static struct ast_generator playtones
Definition: indications.c:256
unsigned int freq1
Definition: indications.h:109
#define M_PI
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:63
char * ast_strip(char *s)
Strip leading/trailing whitespace from a string.
Definition: strings.h:155
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: utils.h:663
#define LOG_ERROR
Definition: logger.h:155
unsigned int time
Definition: indications.h:111
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
#define ast_free(a)
Definition: astmm.h:97
struct playtones_item * items
Definition: indications.c:106
unsigned int modulate
Definition: indications.h:112
#define ast_realloc(a, b)
Definition: astmm.h:103
unsigned int freq2
Definition: indications.h:110
static unsigned int cos
Definition: chan_h323.c:147
static const int midi_tohz[128]
Definition: indications.c:65
int ast_tone_zone_part_parse(const char *s, struct ast_tone_zone_part *tone_data)
Parse a tone part.
Definition: indications.c:262
void ast_playtones_stop ( struct ast_channel chan)

Stop playing tones on a channel.

Parameters
chanthe channel to stop tones on

Definition at line 411 of file indications.c.

References ast_deactivate_generator().

Referenced by ast_app_dtget(), ast_indicate_data(), ast_senddigit_end(), disa_exec(), handle_stopplaytones(), pbx_builtin_waitexten(), playtone(), read_exec(), readexten_exec(), receivefax_t38_init(), sendfax_t38_init(), stop_indicate(), and unistim_indicate().

412 {
414 }
void ast_deactivate_generator(struct ast_channel *chan)
Definition: channel.c:3107
int ast_tone_zone_count ( void  )

Get the number of registered tone zones.

Returns
the total number of registered tone zones

Definition at line 416 of file indications.c.

References ao2_container_count().

417 {
419 }
int ao2_container_count(struct ao2_container *c)
Returns the number of elements in a container.
Definition: astobj2.c:470
static struct ao2_container * ast_tone_zones
Definition: indications.c:81
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.

Return values
<0on error.
0on success.

Definition at line 1127 of file indications.c.

References ast_data_add_node(), ast_data_add_structure, AST_LIST_EMPTY, AST_LIST_TRAVERSE, ast_tone_zone_lock, ast_tone_zone_unlock, ast_tone_zone_sound::entry, and ast_tone_zone::tones.

Referenced by ast_channel_data_add_structure().

1128 {
1129  struct ast_data *data_zone_sound;
1130  struct ast_tone_zone_sound *s;
1131 
1133 
1134  if (AST_LIST_EMPTY(&zone->tones)) {
1135  return 0;
1136  }
1137 
1138  data_zone_sound = ast_data_add_node(tree, "tones");
1139  if (!data_zone_sound) {
1140  return -1;
1141  }
1142 
1143  ast_tone_zone_lock(zone);
1144 
1145  AST_LIST_TRAVERSE(&zone->tones, s, entry) {
1146  ast_data_add_structure(ast_tone_zone_sound, data_zone_sound, s);
1147  }
1148 
1149  ast_tone_zone_unlock(zone);
1150 
1151  return 0;
1152 }
The data tree to be returned by the callbacks and managed by functions local to this file...
Definition: data.c:85
struct ast_tone_zone_sound::@176 entry
Linked list fields for including in the list on an ast_tone_zone.
#define ast_tone_zone_unlock(tz)
Unlock an ast_tone_zone.
Definition: indications.h:192
struct ast_tone_zone::@181 tones
A list of tones for this locale.
#define AST_LIST_EMPTY(head)
Checks whether the specified list contains any entries.
Definition: linkedlists.h:449
A set of tones for a given locale.
Definition: indications.h:73
struct ast_data * ast_data_add_node(struct ast_data *root, const char *childname)
Add a container child.
Definition: data.c:2317
#define ast_data_add_structure(structure_name, root, structure)
Definition: data.h:620
Description of a tone.
Definition: indications.h:36
#define AST_LIST_TRAVERSE(head, var, field)
Loops over (traverses) the entries in a list.
Definition: linkedlists.h:490
#define ast_tone_zone_lock(tz)
Lock an ast_tone_zone.
Definition: indications.h:187
struct ao2_iterator ast_tone_zone_iterator_init ( void  )

Get an iterator for the available tone zones.

Note
Use ao2_iterator_next() to iterate the tone zones.
Use ao2_iterator_destroy() to clean up.
Returns
an initialized iterator

Definition at line 421 of file indications.c.

References ao2_iterator_init().

Referenced by ast_var_indications(), ast_var_indications_table(), and handle_cli_indication_show().

422 {
424 }
static struct ao2_container * ast_tone_zones
Definition: indications.c:81
struct ao2_iterator ao2_iterator_init(struct ao2_container *c, int flags)
Create an iterator for a container.
Definition: astobj2.c:818
int ast_tone_zone_part_parse ( const char *  s,
struct ast_tone_zone_part tone_data 
)

Parse a tone part.

Parameters
sThe part of a tone to parse. This should be in the form described for the data part of ast_tone_zone_sound. '!' should be removed if present.
tone_dataAn output parameter that contains the result of the parsing.
Return values
0success
-1failure, and the contents of tone_data are undefined

Definition at line 262 of file indications.c.

References ast_tone_zone_part::freq1, ast_tone_zone_part::freq2, ast_tone_zone_part::midinote, ast_tone_zone_part::modulate, and ast_tone_zone_part::time.

Referenced by ast_playtones_start().

263 {
264  if (sscanf(s, "%30u+%30u/%30u", &tone_data->freq1, &tone_data->freq2,
265  &tone_data->time) == 3) {
266  /* f1+f2/time format */
267  } else if (sscanf(s, "%30u+%30u", &tone_data->freq1, &tone_data->freq2) == 2) {
268  /* f1+f2 format */
269  tone_data->time = 0;
270  } else if (sscanf(s, "%30u*%30u/%30u", &tone_data->freq1, &tone_data->freq2,
271  &tone_data->time) == 3) {
272  /* f1*f2/time format */
273  tone_data->modulate = 1;
274  } else if (sscanf(s, "%30u*%30u", &tone_data->freq1, &tone_data->freq2) == 2) {
275  /* f1*f2 format */
276  tone_data->time = 0;
277  tone_data->modulate = 1;
278  } else if (sscanf(s, "%30u/%30u", &tone_data->freq1, &tone_data->time) == 2) {
279  /* f1/time format */
280  tone_data->freq2 = 0;
281  } else if (sscanf(s, "%30u", &tone_data->freq1) == 1) {
282  /* f1 format */
283  tone_data->freq2 = 0;
284  tone_data->time = 0;
285  } else if (sscanf(s, "M%30u+M%30u/%30u", &tone_data->freq1, &tone_data->freq2,
286  &tone_data->time) == 3) {
287  /* Mf1+Mf2/time format */
288  tone_data->midinote = 1;
289  } else if (sscanf(s, "M%30u+M%30u", &tone_data->freq1, &tone_data->freq2) == 2) {
290  /* Mf1+Mf2 format */
291  tone_data->time = 0;
292  tone_data->midinote = 1;
293  } else if (sscanf(s, "M%30u*M%30u/%30u", &tone_data->freq1, &tone_data->freq2,
294  &tone_data->time) == 3) {
295  /* Mf1*Mf2/time format */
296  tone_data->modulate = 1;
297  tone_data->midinote = 1;
298  } else if (sscanf(s, "M%30u*M%30u", &tone_data->freq1, &tone_data->freq2) == 2) {
299  /* Mf1*Mf2 format */
300  tone_data->time = 0;
301  tone_data->modulate = 1;
302  tone_data->midinote = 1;
303  } else if (sscanf(s, "M%30u/%30u", &tone_data->freq1, &tone_data->time) == 2) {
304  /* Mf1/time format */
305  tone_data->freq2 = -1;
306  tone_data->midinote = 1;
307  } else if (sscanf(s, "M%30u", &tone_data->freq1) == 1) {
308  /* Mf1 format */
309  tone_data->freq2 = -1;
310  tone_data->time = 0;
311  tone_data->midinote = 1;
312  } else {
313  return -1;
314  }
315 
316  return 0;
317 }
unsigned int midinote
Definition: indications.h:113
unsigned int freq1
Definition: indications.h:109
unsigned int time
Definition: indications.h:111
unsigned int modulate
Definition: indications.h:112
unsigned int freq2
Definition: indications.h:110
static struct ast_tone_zone* ast_tone_zone_ref ( struct ast_tone_zone tz)
static

Increase the reference count on an ast_tone_zone.

Returns
The tone zone provided as an argument

Definition at line 215 of file indications.h.

References ao2_ref, and tz.

Referenced by ast_get_indication_tone(), ast_get_indication_zone(), ast_register_indication_country(), ast_set_indication_country(), and func_channel_write_real().

216 {
217  ao2_ref(tz, +1);
218  return tz;
219 }
static char * tz
Definition: cdr_pgsql.c:56
#define ao2_ref(o, delta)
Definition: astobj2.h:472
static struct ast_tone_zone_sound* ast_tone_zone_sound_ref ( struct ast_tone_zone_sound ts)
static

Increase the reference count on an ast_tone_zone_sound.

Returns
The tone zone sound provided as an argument

Definition at line 237 of file indications.h.

References ao2_ref.

Referenced by ast_get_indication_tone().

238 {
239  ao2_ref(ts, +1);
240  return ts;
241 }
#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)
static