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 * Use ao2_iterator_next() to iterate the tone zones. 00178 * 00179 * \return an initialized iterator 00180 */ 00181 struct ao2_iterator ast_tone_zone_iterator_init(void); 00182 00183 /*! 00184 * \brief Lock an ast_tone_zone 00185 */ 00186 #define ast_tone_zone_lock(tz) ao2_lock(tz) 00187 00188 /*! 00189 * \brief Unlock an ast_tone_zone 00190 */ 00191 #define ast_tone_zone_unlock(tz) ao2_unlock(tz) 00192 00193 /*! 00194 * \brief Trylock an ast_tone_zone 00195 */ 00196 #define ast_tone_zone_trylock(tz) ao2_trylock(tz) 00197 00198 /*! 00199 * \brief Release a reference to an ast_tone_zone 00200 * 00201 * \return NULL 00202 */ 00203 static inline struct ast_tone_zone *ast_tone_zone_unref(struct ast_tone_zone *tz) 00204 { 00205 ao2_ref(tz, -1); 00206 return NULL; 00207 } 00208 00209 /*! 00210 * \brief Increase the reference count on an ast_tone_zone 00211 * 00212 * \return The tone zone provided as an argument 00213 */ 00214 static inline struct ast_tone_zone *ast_tone_zone_ref(struct ast_tone_zone *tz) 00215 { 00216 ao2_ref(tz, +1); 00217 return tz; 00218 } 00219 00220 /*! 00221 * \brief Release a reference to an ast_tone_zone_sound 00222 * 00223 * \return NULL 00224 */ 00225 static inline struct ast_tone_zone_sound *ast_tone_zone_sound_unref(struct ast_tone_zone_sound *ts) 00226 { 00227 ao2_ref(ts, -1); 00228 return NULL; 00229 } 00230 00231 /*! 00232 * \brief Increase the reference count on an ast_tone_zone_sound 00233 * 00234 * \return The tone zone sound provided as an argument 00235 */ 00236 static inline struct ast_tone_zone_sound *ast_tone_zone_sound_ref(struct ast_tone_zone_sound *ts) 00237 { 00238 ao2_ref(ts, +1); 00239 return ts; 00240 } 00241 00242 /*! 00243 * \brief Add a tone_zone structure to the data tree specified. 00244 * 00245 * \retval <0 on error. 00246 * \retval 0 on success. 00247 */ 00248 int ast_tone_zone_data_add_structure(struct ast_data *tree, struct ast_tone_zone *zone); 00249 00250 #endif /* _ASTERISK_INDICATIONS_H */