Tue Aug 20 16:34:34 2013

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 #include "asterisk/utils.h"
00031 #include "asterisk/data.h"
00032 
00033 /*!
00034  * \brief Description of a tone
00035  */
00036 struct ast_tone_zone_sound {
00037    /*! \brief Name of the tone.  For example, "busy". */
00038    const char *name;
00039    /*!
00040     * \brief Description of a tone
00041     *
00042     * The format is a comma separated list of tone parts in the following format:
00043     *
00044     * Format: [!][M]freq[<+|*>freq2][/duration]
00045     *  - '!' - means that the element is NOT repeated
00046     *  - 'M' - interpret the frequencies as midi notes instead of frequencies
00047     *  - freq - The first frequency
00048     *  - freq2 - The second frequency (optional)
00049     *  - '*' - modulate freq by freq2 at a fixed depth of 90%
00050     *  - '+' - combine the frequencies
00051     *  - duration - the length of the tone part (optional, forever if not specified)
00052     */
00053    const char *data;
00054    /*! \brief Linked list fields for including in the list on an ast_tone_zone */
00055    AST_LIST_ENTRY(ast_tone_zone_sound) entry;
00056    /*! \brief Flags only used internally */
00057    union {
00058       uint32_t __padding;
00059       struct {
00060          unsigned int killme:1;
00061       };
00062    };
00063 };
00064 
00065 /*!
00066  * \brief A set of tones for a given locale
00067  *
00068  * \note If a reference to this tone zone is held, then the country
00069  *       is guaranteed not to change.  It is safe to read it without
00070  *       locking the tone zone.  This is not the case for any other
00071  *       field.
00072  */
00073 struct ast_tone_zone {
00074    /*! \brief Country code that this set of tones is for */
00075    char country[16];
00076    /*! 
00077     * \brief Text description of the given country.
00078     *
00079     * This is for nothing more than friendly display to a human.
00080     */
00081    char description[40];
00082    /*! \brief Number of ring cadence elements in the ringcadence array */
00083    unsigned int  nrringcadence;
00084    /*! 
00085     * \brief Array of ring cadence parts
00086     *
00087     * Each element is an amount of time in milliseconds.  The first element
00088     * is for time on, and from there it alternates between on and off.
00089     */
00090    int *ringcadence;
00091    /*! \brief A list of tones for this locale */
00092    AST_LIST_HEAD_NOLOCK(, ast_tone_zone_sound) tones;
00093    /*! \brief Flags only used internally */
00094    union {
00095       uint32_t __padding;
00096       struct {
00097          unsigned int killme:1;
00098       };
00099    };
00100 };
00101 
00102 /*!
00103  * \brief A description of a part of a tone
00104  *
00105  * The elements in this structure map to the format described for the data
00106  * part of the ast_tone_zone_sound struct.
00107  */
00108 struct ast_tone_zone_part {
00109    unsigned int freq1;
00110    unsigned int freq2;
00111    unsigned int time;
00112    unsigned int modulate:1;
00113    unsigned int midinote:1;
00114 };
00115 
00116 /*!
00117  * \brief Parse a tone part
00118  *
00119  * \param s The part of a tone to parse.  This should be in the form described for
00120  *        the data part of ast_tone_zone_sound.  '!' should be removed if present.
00121  * \param tone_data An output parameter that contains the result of the parsing.
00122  *
00123  * \retval 0 success
00124  * \retval -1 failure, and the contents of tone_data are undefined
00125  */
00126 int ast_tone_zone_part_parse(const char *s, struct ast_tone_zone_part *tone_data);
00127 
00128 /*!
00129  * \brief locate ast_tone_zone
00130  *
00131  * \param country country to find.  If NULL is provided, get the default.
00132  *
00133  * \return a reference to the specified country if found or NULL if not found
00134  */
00135 struct ast_tone_zone *ast_get_indication_zone(const char *country);
00136 
00137 /*!
00138  * \brief Locate a tone zone sound
00139  *
00140  * \param zone Zone to look in for a sound, if NULL, the default will be used
00141  * \param indication Sound to look for, such as "busy"
00142  *
00143  * \return a reference to the specified sound if it exists, NULL if not
00144  */
00145 struct ast_tone_zone_sound *ast_get_indication_tone(const struct ast_tone_zone *zone, const char *indication);
00146 
00147 /*!
00148  * \brief Start playing a list of tones on a channel
00149  *
00150  * \param chan the channel to play tones on
00151  * \param vol volume
00152  * \param tonelist the list of tones to play, comma separated
00153  * \param interruptible whether or not this tone can be interrupted
00154  *
00155  * \retval 0 success
00156  * \retval non-zero failure
00157  */
00158 int ast_playtones_start(struct ast_channel *chan, int vol, const char *tonelist, int interruptible);
00159 
00160 /*!
00161  * \brief Stop playing tones on a channel
00162  *
00163  * \param chan the channel to stop tones on
00164  */
00165 void ast_playtones_stop(struct ast_channel *chan);
00166 
00167 /*!
00168  * \brief Get the number of registered tone zones
00169  *
00170  * \return the total number of registered tone zones
00171  */
00172 int ast_tone_zone_count(void);
00173 
00174 /*!
00175  * \brief Get an iterator for the available tone zones
00176  *
00177  * \note Use ao2_iterator_next() to iterate the tone zones.
00178  * \note Use ao2_iterator_destroy() to clean up.
00179  *
00180  * \return an initialized iterator
00181  */
00182 struct ao2_iterator ast_tone_zone_iterator_init(void);
00183 
00184 /*!
00185  * \brief Lock an ast_tone_zone
00186  */
00187 #define ast_tone_zone_lock(tz) ao2_lock(tz)
00188 
00189 /*!
00190  * \brief Unlock an ast_tone_zone
00191  */
00192 #define ast_tone_zone_unlock(tz) ao2_unlock(tz)
00193 
00194 /*!
00195  * \brief Trylock an ast_tone_zone
00196  */
00197 #define ast_tone_zone_trylock(tz) ao2_trylock(tz)
00198 
00199 /*!
00200  * \brief Release a reference to an ast_tone_zone
00201  *
00202  * \return NULL
00203  */
00204 static inline struct ast_tone_zone *ast_tone_zone_unref(struct ast_tone_zone *tz)
00205 {
00206    ao2_ref(tz, -1);
00207    return NULL;
00208 }
00209 
00210 /*!
00211  * \brief Increase the reference count on an ast_tone_zone
00212  *
00213  * \return The tone zone provided as an argument
00214  */
00215 static inline struct ast_tone_zone *ast_tone_zone_ref(struct ast_tone_zone *tz)
00216 {
00217    ao2_ref(tz, +1);
00218    return tz;
00219 }
00220 
00221 /*!
00222  * \brief Release a reference to an ast_tone_zone_sound
00223  *
00224  * \return NULL
00225  */
00226 static inline struct ast_tone_zone_sound *ast_tone_zone_sound_unref(struct ast_tone_zone_sound *ts)
00227 {
00228    ao2_ref(ts, -1);
00229    return NULL;
00230 }
00231 
00232 /*!
00233  * \brief Increase the reference count on an ast_tone_zone_sound
00234  *
00235  * \return The tone zone sound provided as an argument
00236  */
00237 static inline struct ast_tone_zone_sound *ast_tone_zone_sound_ref(struct ast_tone_zone_sound *ts)
00238 {
00239    ao2_ref(ts, +1);
00240    return ts;
00241 }
00242 
00243 /*!
00244  * \brief Add a tone_zone structure to the data tree specified.
00245  *
00246  * \retval <0 on error.
00247  * \retval 0 on success.
00248  */
00249 int ast_tone_zone_data_add_structure(struct ast_data *tree, struct ast_tone_zone *zone);
00250 
00251 #endif /* _ASTERISK_INDICATIONS_H */

Generated on 20 Aug 2013 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1