Mon Oct 8 12:39:23 2012

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

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

ast_tone_zone_soundast_get_indication_tone (const struct ast_tone_zone *zone, const char *indication)
 Locate a tone zone sound.
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.
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.
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_lock ( tz   )     ao2_lock(tz)

Lock an ast_tone_zone.

Definition at line 187 of file indications.h.

Referenced by ast_get_indication_tone(), ast_tone_zone_data_add_structure(), ast_unregister_indication(), ast_var_indications_table(), complete_indications(), handle_cli_indication_add(), handle_cli_indication_show(), is_valid_tone_zone(), parse_tone_zone(), prune_tone_zone(), reset_tone_zone(), and tone_zone_mark().

#define ast_tone_zone_trylock ( tz   )     ao2_trylock(tz)

Trylock an ast_tone_zone.

Definition at line 197 of file indications.h.

#define ast_tone_zone_unlock ( tz   )     ao2_unlock(tz)

Unlock an ast_tone_zone.

Definition at line 192 of file indications.h.

Referenced by ast_get_indication_tone(), ast_tone_zone_data_add_structure(), ast_unregister_indication(), ast_var_indications_table(), complete_indications(), handle_cli_indication_add(), handle_cli_indication_show(), is_valid_tone_zone(), parse_tone_zone(), prune_tone_zone(), reset_tone_zone(), and tone_zone_mark().


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:
zone Zone to look in for a sound, if NULL, the default will be used
indication Sound to look for, such as "busy"
Returns:
a reference to the specified sound if it exists, NULL if not

Definition at line 470 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_zones, default_tone_zone, 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().

00471 {
00472    struct ast_tone_zone_sound *ts = NULL;
00473    /* _zone is const to the users of the API */
00474    struct ast_tone_zone *zone = (struct ast_tone_zone *) _zone;
00475 
00476    /* If no zone is specified, use the default */
00477    if (!zone) {
00478       ao2_lock(ast_tone_zones);
00479       if (default_tone_zone) {
00480          zone = ast_tone_zone_ref(default_tone_zone);
00481       }
00482       ao2_unlock(ast_tone_zones);
00483 
00484       if (!zone) {
00485          return NULL;
00486       }
00487    }
00488 
00489    ast_tone_zone_lock(zone);
00490 
00491    /* Look through list of tones in the zone searching for the right one */
00492    AST_LIST_TRAVERSE(&zone->tones, ts, entry) {
00493       if (!strcasecmp(ts->name, indication)) {
00494          /* Increase ref count for the reference we will return */
00495          ts = ast_tone_zone_sound_ref(ts);
00496          break;
00497       }
00498    }
00499 
00500    ast_tone_zone_unlock(zone);
00501 
00502    return ts;
00503 }

struct ast_tone_zone* ast_get_indication_zone ( const char *  country  ) 

locate ast_tone_zone

Parameters:
country country 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 448 of file indications.c.

References ao2_find, ao2_lock, ao2_unlock, ast_copy_string(), ast_strlen_zero(), ast_tone_zone_ref(), ast_tone_zones, ast_tone_zone::country, default_tone_zone, 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().

00449 {
00450    struct ast_tone_zone *tz = NULL;
00451    struct ast_tone_zone zone_arg = {
00452       .nrringcadence = 0,
00453    };
00454 
00455    if (ast_strlen_zero(country)) {
00456       ao2_lock(ast_tone_zones);
00457       if (default_tone_zone) {
00458          tz = ast_tone_zone_ref(default_tone_zone);
00459       }
00460       ao2_unlock(ast_tone_zones);
00461 
00462       return tz;
00463    }
00464 
00465    ast_copy_string(zone_arg.country, country, sizeof(zone_arg.country));
00466 
00467    return ao2_find(ast_tone_zones, &zone_arg, OBJ_POINTER);
00468 }

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:
chan the channel to play tones on
vol volume
tonelist the list of tones to play, comma separated
interruptible whether or not this tone can be interrupted
Return values:
0 success
non-zero failure

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

00320 {
00321    char *s, *data = ast_strdupa(playlst);
00322    struct playtones_def d = { vol, -1, 0, 1, NULL };
00323    char *stringp;
00324    char *separator;
00325    static const float sample_rate = 8000.0;
00326    static const float max_sample_val = 32768.0;
00327 
00328    if (vol < 1) {
00329       d.vol = 7219; /* Default to -8db */
00330    }
00331 
00332    d.interruptible = interruptible;
00333 
00334    stringp = data;
00335 
00336    /* check if the data is separated with '|' or with ',' by default */
00337    if (strchr(stringp,'|')) {
00338       separator = "|";
00339    } else {
00340       separator = ",";
00341    }
00342 
00343    while ((s = strsep(&stringp, separator)) && !ast_strlen_zero(s)) {
00344       struct ast_tone_zone_part tone_data = {
00345          .time = 0,
00346       };
00347 
00348       s = ast_strip(s);
00349 
00350       if (s[0]=='!') {
00351          s++;
00352       } else if (d.reppos == -1) {
00353          d.reppos = d.nitems;
00354       }
00355 
00356       if (ast_tone_zone_part_parse(s, &tone_data)) {
00357          ast_log(LOG_ERROR, "Failed to parse tone part '%s'\n", s);
00358          continue;
00359       }
00360 
00361       if (tone_data.midinote) {
00362          /* midi notes must be between 0 and 127 */
00363 
00364          if (tone_data.freq1 >= 0 && tone_data.freq1 <= 127) {
00365             tone_data.freq1 = midi_tohz[tone_data.freq1];
00366          } else {
00367             tone_data.freq1 = 0;
00368          }
00369 
00370          if (tone_data.freq2 >= 0 && tone_data.freq2 <= 127) {
00371             tone_data.freq2 = midi_tohz[tone_data.freq2];
00372          } else {
00373             tone_data.freq2 = 0;
00374          }
00375       }
00376 
00377       if (!(d.items = ast_realloc(d.items, (d.nitems + 1) * sizeof(*d.items)))) {
00378          return -1;
00379       }
00380 
00381       d.items[d.nitems].fac1 = 2.0 * cos(2.0 * M_PI * (tone_data.freq1 / sample_rate)) * max_sample_val;
00382       d.items[d.nitems].init_v2_1 = sin(-4.0 * M_PI * (tone_data.freq1 / sample_rate)) * d.vol;
00383       d.items[d.nitems].init_v3_1 = sin(-2.0 * M_PI * (tone_data.freq1 / sample_rate)) * d.vol;
00384 
00385       d.items[d.nitems].fac2 = 2.0 * cos(2.0 * M_PI * (tone_data.freq2 / sample_rate)) * max_sample_val;
00386       d.items[d.nitems].init_v2_2 = sin(-4.0 * M_PI * (tone_data.freq2 / sample_rate)) * d.vol;
00387       d.items[d.nitems].init_v3_2 = sin(-2.0 * M_PI * (tone_data.freq2 / sample_rate)) * d.vol;
00388 
00389       d.items[d.nitems].duration = tone_data.time;
00390       d.items[d.nitems].modulate = tone_data.modulate;
00391 
00392       d.nitems++;
00393    }
00394 
00395    if (!d.nitems) {
00396       ast_log(LOG_ERROR, "No valid tone parts\n");
00397       return -1;
00398    }
00399 
00400    if (ast_activate_generator(chan, &playtones, &d)) {
00401       ast_free(d.items);
00402       return -1;
00403    }
00404 
00405    return 0;
00406 }

void ast_playtones_stop ( struct ast_channel chan  ) 

Stop playing tones on a channel.

Parameters:
chan the channel to stop tones on

Definition at line 408 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().

00409 {
00410    ast_deactivate_generator(chan);
00411 }

int ast_tone_zone_count ( void   ) 

Get the number of registered tone zones.

Returns:
the total number of registered tone zones

Definition at line 413 of file indications.c.

References ao2_container_count(), and ast_tone_zones.

00414 {
00415    return ao2_container_count(ast_tone_zones);
00416 }

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:
<0 on error.
0 on success.

Definition at line 1125 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().

01126 {
01127    struct ast_data *data_zone_sound;
01128    struct ast_tone_zone_sound *s;
01129 
01130    ast_data_add_structure(ast_tone_zone, tree, zone);
01131 
01132    if (AST_LIST_EMPTY(&zone->tones)) {
01133       return 0;
01134    }
01135 
01136    data_zone_sound = ast_data_add_node(tree, "tones");
01137    if (!data_zone_sound) {
01138       return -1;
01139    }
01140 
01141    ast_tone_zone_lock(zone);
01142 
01143    AST_LIST_TRAVERSE(&zone->tones, s, entry) {
01144       ast_data_add_structure(ast_tone_zone_sound, data_zone_sound, s);
01145    }
01146 
01147    ast_tone_zone_unlock(zone);
01148 
01149    return 0;
01150 }

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 418 of file indications.c.

References ao2_iterator_init(), and ast_tone_zones.

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

00419 {
00420    return ao2_iterator_init(ast_tone_zones, 0);
00421 }

int ast_tone_zone_part_parse ( const char *  s,
struct ast_tone_zone_part tone_data 
)

Parse a tone part.

Parameters:
s The 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_data An output parameter that contains the result of the parsing.
Return values:
0 success
-1 failure, 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().

00263 {
00264    if (sscanf(s, "%30u+%30u/%30u", &tone_data->freq1, &tone_data->freq2, 
00265          &tone_data->time) == 3) {
00266       /* f1+f2/time format */
00267    } else if (sscanf(s, "%30u+%30u", &tone_data->freq1, &tone_data->freq2) == 2) {
00268       /* f1+f2 format */
00269       tone_data->time = 0;
00270    } else if (sscanf(s, "%30u*%30u/%30u", &tone_data->freq1, &tone_data->freq2, 
00271          &tone_data->time) == 3) {
00272       /* f1*f2/time format */
00273       tone_data->modulate = 1;
00274    } else if (sscanf(s, "%30u*%30u", &tone_data->freq1, &tone_data->freq2) == 2) {
00275       /* f1*f2 format */
00276       tone_data->time = 0;
00277       tone_data->modulate = 1;
00278    } else if (sscanf(s, "%30u/%30u", &tone_data->freq1, &tone_data->time) == 2) {
00279       /* f1/time format */
00280       tone_data->freq2 = 0;
00281    } else if (sscanf(s, "%30u", &tone_data->freq1) == 1) {
00282       /* f1 format */
00283       tone_data->freq2 = 0;
00284       tone_data->time = 0;
00285    } else if (sscanf(s, "M%30u+M%30u/%30u", &tone_data->freq1, &tone_data->freq2, 
00286          &tone_data->time) == 3) {
00287       /* Mf1+Mf2/time format */
00288       tone_data->midinote = 1;
00289    } else if (sscanf(s, "M%30u+M%30u", &tone_data->freq1, &tone_data->freq2) == 2) {
00290       /* Mf1+Mf2 format */
00291       tone_data->time = 0;
00292       tone_data->midinote = 1;
00293    } else if (sscanf(s, "M%30u*M%30u/%30u", &tone_data->freq1, &tone_data->freq2, 
00294          &tone_data->time) == 3) {
00295       /* Mf1*Mf2/time format */
00296       tone_data->modulate = 1;
00297       tone_data->midinote = 1;
00298    } else if (sscanf(s, "M%30u*M%30u", &tone_data->freq1, &tone_data->freq2) == 2) {
00299       /* Mf1*Mf2 format */
00300       tone_data->time = 0;
00301       tone_data->modulate = 1;
00302       tone_data->midinote = 1;
00303    } else if (sscanf(s, "M%30u/%30u", &tone_data->freq1, &tone_data->time) == 2) {
00304       /* Mf1/time format */
00305       tone_data->freq2 = -1;
00306       tone_data->midinote = 1;
00307    } else if (sscanf(s, "M%30u", &tone_data->freq1) == 1) {
00308       /* Mf1 format */
00309       tone_data->freq2 = -1;
00310       tone_data->time = 0;
00311       tone_data->midinote = 1;
00312    } else {
00313       return -1;
00314    }
00315 
00316    return 0;
00317 }

static struct ast_tone_zone* ast_tone_zone_ref ( struct ast_tone_zone tz  )  [inline, 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().

00216 {
00217    ao2_ref(tz, +1);
00218    return tz;
00219 }

static struct ast_tone_zone_sound* ast_tone_zone_sound_ref ( struct ast_tone_zone_sound ts  )  [inline, 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().

00238 {
00239    ao2_ref(ts, +1);
00240    return ts;
00241 }

static struct ast_tone_zone_sound* ast_tone_zone_sound_unref ( struct ast_tone_zone_sound ts  )  [inline, static]

Release a reference to an ast_tone_zone_sound.

Returns:
NULL

Definition at line 226 of file indications.h.

References ao2_ref.

Referenced by ast_app_dtget(), ast_indicate_data(), ast_register_indication(), ast_tone_zone_destructor(), ast_unregister_indication(), dial_handle_playtones(), handle_playtones(), in_band_indication(), pbx_builtin_waitexten(), play_dialtone(), prune_tone_zone(), read_exec(), readexten_exec(), skinny_transfer(), and stop_indicate().

00227 {
00228    ao2_ref(ts, -1);
00229    return NULL;
00230 }

static struct ast_tone_zone* ast_tone_zone_unref ( struct ast_tone_zone tz  )  [inline, static]

Release a reference to an ast_tone_zone.

Returns:
NULL

Definition at line 204 of file indications.h.

References ao2_ref, and tz.

Referenced by ast_channel_destructor(), ast_set_indication_country(), ast_unregister_indication_country(), ast_var_indications(), ast_var_indications_table(), build_device(), complete_country(), complete_indications(), func_channel_write_real(), handle_cli_indication_add(), handle_cli_indication_remove(), handle_cli_indication_show(), parse_tone_zone(), and reload_config().

00205 {
00206    ao2_ref(tz, -1);
00207    return NULL;
00208 }


Generated on Mon Oct 8 12:39:23 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7