indications.h File Reference

Tone Indication Support. More...

#include "asterisk/astobj2.h"
#include "asterisk/utils.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...

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...
#define	MAX_TONEZONE_COUNTRY   16

Functions
struct ast_tone_zone_sound *	ast_get_indication_tone (const struct ast_tone_zone *zone, const char *indication)
	Locate a tone zone sound. More...
struct ast_tone_zone *	ast_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...
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_zone *	ast_tone_zone_ref (struct ast_tone_zone *tz)
	Increase the reference count on an ast_tone_zone. More...
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. More...
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. More...
static struct ast_tone_zone *	ast_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

ast_tone_zone_lock

#define ast_tone_zone_lock

(

tz

)

ao2_lock(tz)

Lock an ast_tone_zone.

Definition at line 188 of file indications.h.

ast_tone_zone_trylock

#define ast_tone_zone_trylock

(

tz

)

ao2_trylock(tz)

Trylock an ast_tone_zone.

Definition at line 198 of file indications.h.

ast_tone_zone_unlock

#define ast_tone_zone_unlock

(

tz

)

ao2_unlock(tz)

Unlock an ast_tone_zone.

Definition at line 193 of file indications.h.

MAX_TONEZONE_COUNTRY

#define MAX_TONEZONE_COUNTRY   16

Definition at line 64 of file indications.h.

Function Documentation

ast_get_indication_tone()

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

{
    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);
 
    if (!_zone)
        zone = ast_tone_zone_unref(zone);
 
    return ts;
}

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_unref(), ast_tone_zones, default_tone_zone, ast_tone_zone_sound::name, NULL, and ast_tone_zone::tones.

Referenced by ast_app_dtget(), ast_control_tone(), dial_handle_playtones(), handle_playtones(), in_band_indication(), indicate_data_internal(), pbx_builtin_waitexten(), play_dialtone(), read_exec(), readexten_exec(), and send_dial_tone().

ast_get_indication_zone()

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

locate ast_tone_zone

Definition at line 439 of file indications.c.

{
    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);
}

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

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

ast_playtones_start()

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

{
    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 playtones_item *new_items;
        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 <= 127) {
                tone_data.freq1 = midi_tohz[tone_data.freq1];
            } else {
                tone_data.freq1 = 0;
            }
 
            if (tone_data.freq2 <= 127) {
                tone_data.freq2 = midi_tohz[tone_data.freq2];
            } else {
                tone_data.freq2 = 0;
            }
        }
 
        new_items = ast_realloc(d.items, (d.nitems + 1) * sizeof(*d.items));
        if (!new_items) {
            ast_free(d.items);
            return -1;
        }
        d.items = new_items;
 
        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;
}

References ast_activate_generator(), ast_free, ast_log, ast_realloc, ast_strdupa, ast_strip(), ast_strlen_zero(), ast_tone_zone_part_parse(), cos, d, ast_tone_zone_part::freq1, ast_tone_zone_part::freq2, playtones_def::interruptible, LOG_ERROR, M_PI, midi_tohz, ast_tone_zone_part::midinote, ast_tone_zone_part::modulate, NULL, playtones, strsep(), ast_tone_zone_part::time, and playtones_def::vol.

Referenced by ast_app_dtget(), ast_control_tone(), ast_senddigit_begin(), ast_senddigit_mf_begin(), control_tone_frame_response(), dial_handle_playtones(), handle_playtones(), in_band_indication(), indicate_data_internal(), mf_stream(), milliwatt_exec(), pbx_builtin_waitexten(), play_dialtone(), playtone(), read_exec(), readexten_exec(), receivefax_t38_init(), send_tone_burst(), sendfax_t38_init(), and sf_stream().

ast_playtones_stop()

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

{
    ast_deactivate_generator(chan);
}

References ast_deactivate_generator().

Referenced by ast_app_dtget(), ast_senddigit_end(), ast_senddigit_mf_end(), control_tone_frame_response(), disa_exec(), handle_stopplaytones(), indicate_data_internal(), pbx_builtin_waitexten(), playtone(), read_exec(), readexten_exec(), receivefax_t38_init(), send_tone_burst(), sendfax_t38_init(), and unistim_indicate().

ast_tone_zone_count()

int ast_tone_zone_count

(

void

)

Get the number of registered tone zones.

Returns

the total number of registered tone zones

Definition at line 398 of file indications.c.

{
    return ao2_container_count(ast_tone_zones);
}

References ao2_container_count(), and ast_tone_zones.

ast_tone_zone_iterator_init()

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

{
    return ao2_iterator_init(ast_tone_zones, 0);
}

References ao2_iterator_init(), and ast_tone_zones.

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

ast_tone_zone_part_parse()

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

{
    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;
}

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

ast_tone_zone_ref()

static struct ast_tone_zone * ast_tone_zone_ref ( struct ast_tone_zone *  tz )

inlinestatic

Increase the reference count on an ast_tone_zone.

Returns

The tone zone provided as an argument

Definition at line 216 of file indications.h.

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

References ao2_ref, and tz.

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

ast_tone_zone_sound_ref()

static struct ast_tone_zone_sound * ast_tone_zone_sound_ref ( struct ast_tone_zone_sound *  ts )

inlinestatic

Increase the reference count on an ast_tone_zone_sound.

Returns

The tone zone sound provided as an argument

Definition at line 238 of file indications.h.

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

References ao2_ref.

Referenced by ast_get_indication_tone().

ast_tone_zone_sound_unref()

static struct ast_tone_zone_sound * ast_tone_zone_sound_unref ( struct ast_tone_zone_sound *  ts )

inlinestatic

Release a reference to an ast_tone_zone_sound.

Returns

NULL

Definition at line 227 of file indications.h.

{
    ao2_ref(ts, -1);
    return NULL;
}

References ao2_ref, and NULL.

Referenced by ast_app_dtget(), ast_control_tone(), ast_register_indication(), ast_tone_zone_destructor(), ast_unregister_indication(), dial_handle_playtones(), handle_playtones(), in_band_indication(), indicate_data_internal(), pbx_builtin_waitexten(), play_dialtone(), prune_tone_zone(), read_exec(), readexten_exec(), and send_dial_tone().

ast_tone_zone_unref()

static struct ast_tone_zone * ast_tone_zone_unref ( struct ast_tone_zone *  tz )

inlinestatic

Release a reference to an ast_tone_zone.

Returns

NULL

Definition at line 205 of file indications.h.

{
    ao2_ref(tz, -1);
    return NULL;
}

References ao2_ref, NULL, and tz.

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