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 <middelink@polyware.nl>
 * \author Russell Bryant <russell@digium.com>
 */
 
#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 */