Thu Apr 28 2011 17:13:56

Asterisk developer's documentation


indications.h File Reference

Tone Indication Support. More...

#include "asterisk/astobj2.h"
Include dependency graph for indications.h:
This graph shows which files directly or indirectly include this file:

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...

Defines

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

Functions

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

Detailed Description

Tone Indication Support.

Author:
Pauline Middelink <middelink@polyware.nl>
Russell Bryant <russell@digium.com>

Definition in file indications.h.


Define Documentation

#define ast_tone_zone_trylock (   tz)    ao2_trylock(tz)

Trylock an ast_tone_zone.

Definition at line 194 of file indications.h.


Function Documentation

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

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 452 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(), dialtone_indicate(), handle_playtones(), in_band_indication(), pbx_builtin_waitexten(), play_dialtone(), read_exec(), readexten_exec(), and skinny_transfer().

{
   struct ast_tone_zone_sound *ts = NULL;
   /* _zone is const to the users of the API */
   struct ast_tone_zone *zone = (struct ast_tone_zone *) _zone;

   /* If no zone is specified, use the default */
   if (!zone) {
      ao2_lock(ast_tone_zones);
      if (default_tone_zone) {
         zone = ast_tone_zone_ref(default_tone_zone);
      }
      ao2_unlock(ast_tone_zones);

      if (!zone) {
         return NULL;
      }
   }

   ast_tone_zone_lock(zone);

   /* Look through list of tones in the zone searching for the right one */
   AST_LIST_TRAVERSE(&zone->tones, ts, entry) {
      if (!strcasecmp(ts->name, indication)) {
         /* Increase ref count for the reference we will return */
         ts = ast_tone_zone_sound_ref(ts);
         break;
      }
   }

   ast_tone_zone_unlock(zone);

   return ts;
}
struct ast_tone_zone* ast_get_indication_zone ( const char *  country) [read]

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 430 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, and OBJ_POINTER.

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

{
   struct ast_tone_zone *tz = NULL;
   struct ast_tone_zone zone_arg = {
      .nrringcadence = 0,
   };

   if (ast_strlen_zero(country)) {
      ao2_lock(ast_tone_zones);
      if (default_tone_zone) {
         tz = ast_tone_zone_ref(default_tone_zone);
      }
      ao2_unlock(ast_tone_zones);

      return tz;
   }

   ast_copy_string(zone_arg.country, country, sizeof(zone_arg.country));

   return ao2_find(ast_tone_zones, &zone_arg, OBJ_POINTER);
}
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 301 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, ast_tone_zone_part::midinote, ast_tone_zone_part::modulate, playtones_item::modulate, playtones_def::nitems, playtones_def::reppos, s, strsep(), ast_tone_zone_part::time, and playtones_def::vol.

{
   char *s, *data = ast_strdupa(playlst);
   struct playtones_def d = { vol, -1, 0, 1, NULL };
   char *stringp;
   char *separator;
   static const float sample_rate = 8000.0;
   static const float max_sample_val = 32768.0;

   if (vol < 1) {
      d.vol = 7219; /* Default to -8db */
   }

   d.interruptible = interruptible;

   stringp = data;

   /* check if the data is separated with '|' or with ',' by default */
   if (strchr(stringp,'|')) {
      separator = "|";
   } else {
      separator = ",";
   }

   while ((s = strsep(&stringp, separator)) && !ast_strlen_zero(s)) {
      struct ast_tone_zone_part tone_data = {
         .time = 0,
      };

      s = ast_strip(s);

      if (s[0]=='!') {
         s++;
      } else if (d.reppos == -1) {
         d.reppos = d.nitems;
      }

      if (ast_tone_zone_part_parse(s, &tone_data)) {
         ast_log(LOG_ERROR, "Failed to parse tone part '%s'\n", s);
         continue;
      }

      if (tone_data.midinote) {
         /* midi notes must be between 0 and 127 */

         if (tone_data.freq1 >= 0 && tone_data.freq1 <= 127) {
            tone_data.freq1 = midi_tohz[tone_data.freq1];
         } else {
            tone_data.freq1 = 0;
         }

         if (tone_data.freq2 >= 0 && tone_data.freq2 <= 127) {
            tone_data.freq2 = midi_tohz[tone_data.freq2];
         } else {
            tone_data.freq2 = 0;
         }
      }

      if (!(d.items = ast_realloc(d.items, (d.nitems + 1) * sizeof(*d.items)))) {
         return -1;
      }

      d.items[d.nitems].fac1 = 2.0 * cos(2.0 * M_PI * (tone_data.freq1 / sample_rate)) * max_sample_val;
      d.items[d.nitems].init_v2_1 = sin(-4.0 * M_PI * (tone_data.freq1 / sample_rate)) * d.vol;
      d.items[d.nitems].init_v3_1 = sin(-2.0 * M_PI * (tone_data.freq1 / sample_rate)) * d.vol;

      d.items[d.nitems].fac2 = 2.0 * cos(2.0 * M_PI * (tone_data.freq2 / sample_rate)) * max_sample_val;
      d.items[d.nitems].init_v2_2 = sin(-4.0 * M_PI * (tone_data.freq2 / sample_rate)) * d.vol;
      d.items[d.nitems].init_v3_2 = sin(-2.0 * M_PI * (tone_data.freq2 / sample_rate)) * d.vol;

      d.items[d.nitems].duration = tone_data.time;
      d.items[d.nitems].modulate = tone_data.modulate;

      d.nitems++;
   }

   if (!d.nitems) {
      ast_log(LOG_ERROR, "No valid tone parts\n");
      return -1;
   }

   if (ast_activate_generator(chan, &playtones, &d)) {
      ast_free(d.items);
      return -1;
   }

   return 0;
}
void ast_playtones_stop ( struct ast_channel chan)

Stop playing tones on a channel.

Parameters:
chanthe channel to stop tones on

Stop the tones from playing

Definition at line 390 of file indications.c.

References ast_deactivate_generator().

int ast_tone_zone_count ( void  )

Get the number of registered tone zones.

Returns:
the total number of registered tone zones

Definition at line 395 of file indications.c.

References ao2_container_count().

struct ao2_iterator ast_tone_zone_iterator_init ( void  ) [read]

Get an iterator for the available tone zones.

Use ao2_iterator_next() to iterate the tone zones.

Returns:
an initialized iterator

Definition at line 400 of file indications.c.

References ao2_iterator_init().

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

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 244 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().

{
   if (sscanf(s, "%30u+%30u/%30u", &tone_data->freq1, &tone_data->freq2, 
         &tone_data->time) == 3) {
      /* f1+f2/time format */
   } else if (sscanf(s, "%30u+%30u", &tone_data->freq1, &tone_data->freq2) == 2) {
      /* f1+f2 format */
      tone_data->time = 0;
   } else if (sscanf(s, "%30u*%30u/%30u", &tone_data->freq1, &tone_data->freq2, 
         &tone_data->time) == 3) {
      /* f1*f2/time format */
      tone_data->modulate = 1;
   } else if (sscanf(s, "%30u*%30u", &tone_data->freq1, &tone_data->freq2) == 2) {
      /* f1*f2 format */
      tone_data->time = 0;
      tone_data->modulate = 1;
   } else if (sscanf(s, "%30u/%30u", &tone_data->freq1, &tone_data->time) == 2) {
      /* f1/time format */
      tone_data->freq2 = 0;
   } else if (sscanf(s, "%30u", &tone_data->freq1) == 1) {
      /* f1 format */
      tone_data->freq2 = 0;
      tone_data->time = 0;
   } else if (sscanf(s, "M%30u+M%30u/%30u", &tone_data->freq1, &tone_data->freq2, 
         &tone_data->time) == 3) {
      /* Mf1+Mf2/time format */
      tone_data->midinote = 1;
   } else if (sscanf(s, "M%30u+M%30u", &tone_data->freq1, &tone_data->freq2) == 2) {
      /* Mf1+Mf2 format */
      tone_data->time = 0;
      tone_data->midinote = 1;
   } else if (sscanf(s, "M%30u*M%30u/%30u", &tone_data->freq1, &tone_data->freq2, 
         &tone_data->time) == 3) {
      /* Mf1*Mf2/time format */
      tone_data->modulate = 1;
      tone_data->midinote = 1;
   } else if (sscanf(s, "M%30u*M%30u", &tone_data->freq1, &tone_data->freq2) == 2) {
      /* Mf1*Mf2 format */
      tone_data->time = 0;
      tone_data->modulate = 1;
      tone_data->midinote = 1;
   } else if (sscanf(s, "M%30u/%30u", &tone_data->freq1, &tone_data->time) == 2) {
      /* Mf1/time format */
      tone_data->freq2 = -1;
      tone_data->midinote = 1;
   } else if (sscanf(s, "M%30u", &tone_data->freq1) == 1) {
      /* Mf1 format */
      tone_data->freq2 = -1;
      tone_data->time = 0;
      tone_data->midinote = 1;
   } else {
      return -1;
   }

   return 0;
}
static struct ast_tone_zone* ast_tone_zone_ref ( struct ast_tone_zone tz) [static, read]

Increase the reference count on an ast_tone_zone.

Returns:
The tone zone provided as an argument

Definition at line 212 of file indications.h.

References ao2_ref.

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

{
   ao2_ref(tz, +1);
   return tz;
}
static struct ast_tone_zone_sound* ast_tone_zone_sound_ref ( struct ast_tone_zone_sound ts) [static, read]

Increase the reference count on an ast_tone_zone_sound.

Returns:
The tone zone sound provided as an argument

Definition at line 234 of file indications.h.

References ao2_ref.

Referenced by ast_get_indication_tone().

{
   ao2_ref(ts, +1);
   return ts;
}