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