indications.h

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2002, Pauline Middelink
 * Copyright (C) 2009, Digium, Inc.
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

/*!
 * \file
 * \brief Tone Indication Support
 *
 * \author Pauline Middelink <[email protected]>
 * \author Russell Bryant <[email protected]>
 */

#ifndef _ASTERISK_INDICATIONS_H
#define _ASTERISK_INDICATIONS_H

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

/*!
 * \brief Description of a tone
 */
struct ast_tone_zone_sound {
 /*! \brief Name of the tone. For example, "busy". */
 const char *name;
 /*!
 * \brief Description of a tone
 *
 * The format is a comma separated list of tone parts in the following format:
 *
 * Format: [!][M]freq[<+|*>freq2][/duration]
 * - '!' - means that the element is NOT repeated
 * - 'M' - interpret the frequencies as midi notes instead of frequencies
 * - freq - The first frequency
 * - freq2 - The second frequency (optional)
 * - '*' - modulate freq by freq2 at a fixed depth of 90%
 * - '+' - combine the frequencies
 * - duration - the length of the tone part (optional, forever if not specified)
 */
 const char *data;
 /*! \brief Linked list fields for including in the list on an ast_tone_zone */
 AST_LIST_ENTRY(ast_tone_zone_sound) entry;
 /*! \brief Flags only used internally */
 union {
 uint32_t __padding;
 struct {
 unsigned int killme:1;
 };
 };
};

#define MAX_TONEZONE_COUNTRY 16

/*!
 * \brief A set of tones for a given locale
 *
 * \note If a reference to this tone zone is held, then the country
 * is guaranteed not to change. It is safe to read it without
 * locking the tone zone. This is not the case for any other
 * field.
 */
struct ast_tone_zone {
 /*! \brief Country code that this set of tones is for */
 char country[MAX_TONEZONE_COUNTRY];
 /*!
 * \brief Text description of the given country.
 *
 * This is for nothing more than friendly display to a human.
 */
 char description[40];
 /*! \brief Number of ring cadence elements in the ringcadence array */
 unsigned int nrringcadence;
 /*!
 * \brief Array of ring cadence parts
 *
 * Each element is an amount of time in milliseconds. The first element
 * is for time on, and from there it alternates between on and off.
 */
 int *ringcadence;
 /*! \brief A list of tones for this locale */
 AST_LIST_HEAD_NOLOCK(, ast_tone_zone_sound) tones;
 /*! \brief Flags only used internally */
 union {
 uint32_t __padding;
 struct {
 unsigned int killme:1;
 };
 };
};

/*!
 * \brief A description of a part of a tone
 *
 * The elements in this structure map to the format described for the data
 * part of the ast_tone_zone_sound struct.
 */
struct ast_tone_zone_part {
 unsigned int freq1;
 unsigned int freq2;
 unsigned int time;
 unsigned int modulate:1;
 unsigned int midinote:1;
};

/*!
 * \brief Parse a tone part
 *
 * \param 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.
 * \param tone_data An output parameter that contains the result of the parsing.
 *
 * \retval 0 success
 * \retval -1 failure, and the contents of tone_data are undefined
 */
int ast_tone_zone_part_parse(const char *s, struct ast_tone_zone_part *tone_data);

/*!
 * \brief locate ast_tone_zone
 *
 * \param country country to find. If NULL is provided, get the default.
 *
 * \return a reference to the specified country if found or NULL if not found
 */
struct ast_tone_zone *ast_get_indication_zone(const char *country);

/*!
 * \brief Locate a tone zone sound
 *
 * \param zone Zone to look in for a sound, if NULL, the default will be used
 * \param indication Sound to look for, such as "busy"
 *
 * \return a reference to the specified sound if it exists, NULL if not
 */
struct ast_tone_zone_sound *ast_get_indication_tone(const struct ast_tone_zone *zone, const char *indication);

/*!
 * \brief Start playing a list of tones on a channel
 *
 * \param chan the channel to play tones on
 * \param vol volume
 * \param tonelist the list of tones to play, comma separated
 * \param interruptible whether or not this tone can be interrupted
 *
 * \retval 0 success
 * \retval non-zero failure
 */
int ast_playtones_start(struct ast_channel *chan, int vol, const char *tonelist, int interruptible);

/*!
 * \brief Stop playing tones on a channel
 *
 * \param chan the channel to stop tones on
 */
void ast_playtones_stop(struct ast_channel *chan);

/*!
 * \brief Get the number of registered tone zones
 *
 * \return the total number of registered tone zones
 */
int ast_tone_zone_count(void);

/*!
 * \brief Get an iterator for the available tone zones
 *
 * \note Use ao2_iterator_next() to iterate the tone zones.
 * \note Use ao2_iterator_destroy() to clean up.
 *
 * \return an initialized iterator
 */
struct ao2_iterator ast_tone_zone_iterator_init(void);

/*!
 * \brief Lock an ast_tone_zone
 */
#define ast_tone_zone_lock(tz) ao2_lock(tz)

/*!
 * \brief Unlock an ast_tone_zone
 */
#define ast_tone_zone_unlock(tz) ao2_unlock(tz)

/*!
 * \brief Trylock an ast_tone_zone
 */
#define ast_tone_zone_trylock(tz) ao2_trylock(tz)

/*!
 * \brief Release a reference to an ast_tone_zone
 *
 * \return NULL
 */
static inline struct ast_tone_zone *ast_tone_zone_unref(struct ast_tone_zone *tz)
{
 ao2_ref(tz, -1);
 return NULL;
}

/*!
 * \brief Increase the reference count on an ast_tone_zone
 *
 * \return The tone zone provided as an argument
 */
static inline struct ast_tone_zone *ast_tone_zone_ref(struct ast_tone_zone *tz)
{
 ao2_ref(tz, +1);
 return tz;
}

/*!
 * \brief Release a reference to an ast_tone_zone_sound
 *
 * \return NULL
 */
static inline struct ast_tone_zone_sound *ast_tone_zone_sound_unref(struct ast_tone_zone_sound *ts)
{
 ao2_ref(ts, -1);
 return NULL;
}

/*!
 * \brief Increase the reference count on an ast_tone_zone_sound
 *
 * \return The tone zone sound provided as an argument
 */
static inline struct ast_tone_zone_sound *ast_tone_zone_sound_ref(struct ast_tone_zone_sound *ts)
{
 ao2_ref(ts, +1);
 return ts;
}

#endif /* _ASTERISK_INDICATIONS_H */