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 */