Thu Apr 28 2011 17:15:23

Asterisk developer's documentation


indications.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2002, Pauline Middelink
00005  * Copyright (C) 2009, Digium, Inc.
00006  *
00007  * See http://www.asterisk.org for more information about
00008  * the Asterisk project. Please do not directly contact
00009  * any of the maintainers of this project for assistance;
00010  * the project provides a web site, mailing lists and IRC
00011  * channels for your use.
00012  *
00013  * This program is free software, distributed under the terms of
00014  * the GNU General Public License Version 2. See the LICENSE file
00015  * at the top of the source tree.
00016  */
00017 
00018 /*!
00019  * \file
00020  * \brief Tone Indication Support
00021  *
00022  * \author Pauline Middelink <middelink@polyware.nl>
00023  * \author Russell Bryant <russell@digium.com>
00024  */
00025 
00026 #ifndef _ASTERISK_INDICATIONS_H
00027 #define _ASTERISK_INDICATIONS_H
00028 
00029 #include "asterisk/astobj2.h"
00030 
00031 /*!
00032  * \brief Description of a tone
00033  */
00034 struct ast_tone_zone_sound {
00035    /*! \brief Name of the tone.  For example, "busy". */
00036    const char *name;
00037    /*!
00038     * \brief Description of a tone
00039     *
00040     * The format is a comma separated list of tone parts in the following format:
00041     *
00042     * Format: [!][M]freq[<+|*>freq2][/duration]
00043     *  - '!' - means that the element is NOT repeated
00044     *  - 'M' - interpret the frequencies as midi notes instead of frequencies
00045     *  - freq - The first frequency
00046     *  - freq2 - The second frequency (optional)
00047     *  - '*' - modulate freq by freq2 at a fixed depth of 90%
00048     *  - '+' - combine the frequencies
00049     *  - duration - the length of the tone part (optional, forever if not specified)
00050     */
00051    const char *data;
00052    /*! \brief Linked list fields for including in the list on an ast_tone_zone */
00053    AST_LIST_ENTRY(ast_tone_zone_sound) entry;
00054    /*! \brief Flags only used internally */
00055    union {
00056       uint32_t __padding;
00057       struct {
00058          unsigned int killme:1;
00059       };
00060    };
00061 };
00062 
00063 /*!
00064  * \brief A set of tones for a given locale
00065  *
00066  * \note If a reference to this tone zone is held, then the country
00067  *       is guaranteed not to change.  It is safe to read it without
00068  *       locking the tone zone.  This is not the case for any other
00069  *       field.
00070  */
00071 struct ast_tone_zone {
00072    /*! \brief Country code that this set of tones is for */
00073    char country[5];
00074    /*! 
00075     * \brief Text description of the given country.
00076     *
00077     * This is for nothing more than friendly display to a human.
00078     */
00079    char description[40];
00080    /*! \brief Number of ring cadence elements in the ringcadence array */
00081    unsigned int  nrringcadence;
00082    /*! 
00083     * \brief Array of ring cadence parts
00084     *
00085     * Each element is an amount of time in milliseconds.  The first element
00086     * is for time on, and from there it alternates between on and off.
00087     */
00088    int *ringcadence;
00089    /*! \brief A list of tones for this locale */
00090    AST_LIST_HEAD_NOLOCK(, ast_tone_zone_sound) tones;
00091    /*! \brief Flags only used internally */
00092    union {
00093       uint32_t __padding;
00094       struct {
00095          unsigned int killme:1;
00096       };
00097    };
00098 };
00099 
00100 /*!
00101  * \brief A description of a part of a tone
00102  *
00103  * The elements in this structure map to the format described for the data
00104  * part of the ast_tone_zone_sound struct.
00105  */
00106 struct ast_tone_zone_part {
00107    unsigned int freq1;
00108    unsigned int freq2;
00109    unsigned int time;
00110    unsigned int modulate:1;
00111    unsigned int midinote:1;
00112 };
00113 
00114 /*!
00115  * \brief Parse a tone part
00116  *
00117  * \param s The part of a tone to parse.  This should be in the form described for
00118  *        the data part of ast_tone_zone_sound.  '!' should be removed if present.
00119  * \param tone_data An output parameter that contains the result of the parsing.
00120  *
00121  * \retval 0 success
00122  * \retval -1 failure, and the contents of tone_data are undefined
00123  */
00124 int ast_tone_zone_part_parse(const char *s, struct ast_tone_zone_part *tone_data);
00125 
00126 /*!
00127  * \brief locate ast_tone_zone
00128  *
00129  * \param country country to find.  If NULL is provided, get the default.
00130  *
00131  * \return a reference to the specified country if found or NULL if not found
00132  */
00133 struct ast_tone_zone *ast_get_indication_zone(const char *country);
00134 
00135 /*!
00136  * \brief Locate a tone zone sound
00137  *
00138  * \param zone Zone to look in for a sound, if NULL, the default will be used
00139  * \param indication Sound to look for, such as "busy"
00140  *
00141  * \return a reference to the specified sound if it exists, NULL if not
00142  */
00143 struct ast_tone_zone_sound *ast_get_indication_tone(const struct ast_tone_zone *zone, const char *indication);
00144 
00145 /*!
00146  * \brief Start playing a list of tones on a channel
00147  *
00148  * \param chan the channel to play tones on
00149  * \param vol volume
00150  * \param tonelist the list of tones to play, comma separated
00151  * \param interruptible whether or not this tone can be interrupted
00152  *
00153  * \retval 0 success
00154  * \retval non-zero failure
00155  */
00156 int ast_playtones_start(struct ast_channel *chan, int vol, const char *tonelist, int interruptible);
00157 
00158 /*!
00159  * \brief Stop playing tones on a channel
00160  *
00161  * \param chan the channel to stop tones on
00162  */
00163 void ast_playtones_stop(struct ast_channel *chan);
00164 
00165 /*!
00166  * \brief Get the number of registered tone zones
00167  *
00168  * \return the total number of registered tone zones
00169  */
00170 int ast_tone_zone_count(void);
00171 
00172 /*!
00173  * \brief Get an iterator for the available tone zones
00174  *
00175  * Use ao2_iterator_next() to iterate the tone zones.
00176  *
00177  * \return an initialized iterator
00178  */
00179 struct ao2_iterator ast_tone_zone_iterator_init(void);
00180 
00181 /*!
00182  * \brief Lock an ast_tone_zone
00183  */
00184 #define ast_tone_zone_lock(tz) ao2_lock(tz)
00185 
00186 /*!
00187  * \brief Unlock an ast_tone_zone
00188  */
00189 #define ast_tone_zone_unlock(tz) ao2_unlock(tz)
00190 
00191 /*!
00192  * \brief Trylock an ast_tone_zone
00193  */
00194 #define ast_tone_zone_trylock(tz) ao2_trylock(tz)
00195 
00196 /*!
00197  * \brief Release a reference to an ast_tone_zone
00198  *
00199  * \return NULL
00200  */
00201 static inline struct ast_tone_zone *ast_tone_zone_unref(struct ast_tone_zone *tz)
00202 {
00203    ao2_ref(tz, -1);
00204    return NULL;
00205 }
00206 
00207 /*!
00208  * \brief Increase the reference count on an ast_tone_zone
00209  *
00210  * \return The tone zone provided as an argument
00211  */
00212 static inline struct ast_tone_zone *ast_tone_zone_ref(struct ast_tone_zone *tz)
00213 {
00214    ao2_ref(tz, +1);
00215    return tz;
00216 }
00217 
00218 /*!
00219  * \brief Release a reference to an ast_tone_zone_sound
00220  *
00221  * \return NULL
00222  */
00223 static inline struct ast_tone_zone_sound *ast_tone_zone_sound_unref(struct ast_tone_zone_sound *ts)
00224 {
00225    ao2_ref(ts, -1);
00226    return NULL;
00227 }
00228 
00229 /*!
00230  * \brief Increase the reference count on an ast_tone_zone_sound
00231  *
00232  * \return The tone zone sound provided as an argument
00233  */
00234 static inline struct ast_tone_zone_sound *ast_tone_zone_sound_ref(struct ast_tone_zone_sound *ts)
00235 {
00236    ao2_ref(ts, +1);
00237    return ts;
00238 }
00239 
00240 #endif /* _ASTERISK_INDICATIONS_H */