Asterisk - The Open Source Telephony Project  18.5.0
say.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <[email protected]>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18 
19 /*! \file
20  * \brief Say numbers and dates (maybe words one day too)
21  */
22 
23 #ifndef _ASTERISK_SAY_H
24 #define _ASTERISK_SAY_H
25 
26 #include "asterisk/channel.h"
27 #include "asterisk/file.h"
28 
29 #include <time.h>
30 
31 #if defined(__cplusplus) || defined(c_plusplus)
32 extern "C" {
33 #endif
34 
35 /*! \brief
36  * The basic ast_say_* functions are implemented as function pointers,
37  * initialized to the function say_stub() which simply returns an error.
38  * Other interfaces, declared here as regular functions, are simply
39  * wrappers around the basic functions.
40  *
41  * An implementation of the basic ast_say functions (e.g. from say.c or from
42  * a dynamically loaded module) will just have to reassign the pointers
43  * to the relevant functions to override the previous implementation.
44  *
45  * \todo XXX
46  * As the conversion from the old implementation of say.c to the new
47  * implementation will be completed, and the API suitably reworked by
48  * removing redundant functions and/or arguments, this mechanism may be
49  * reverted back to pure static functions, if needed.
50  */
51 #if defined(SAY_STUBS)
52 /* provide declarations for the *say*() functions
53  * and initialize them to the stub function
54  */
55 static int say_stub(struct ast_channel *chan, ...)
56 {
57  ast_log(LOG_WARNING, "no implementation for the say() functions\n");
58  return -1;
59 };
60 
61 #undef SAY_STUBS
62 #define SAY_INIT(x) = (typeof (x))say_stub
63 #define SAY_EXTERN
64 #else
65 #define SAY_INIT(x)
66 #define SAY_EXTERN extern
67 #endif
68 
69 /*!
70  * \brief says a number
71  * \param chan channel to say them number on
72  * \param num number to say on the channel
73  * \param ints which dtmf to interrupt on
74  * \param lang language to speak the number
75  * \param options set to 'f' for female, 'm' for male, 'c' for commune, 'n' for neuter
76  * \details
77  * Vocally says a number on a given channel
78  * \retval 0 on success
79  * \retval DTMF digit on interrupt
80  * \retval -1 on failure
81  */
82 int ast_say_number(struct ast_channel *chan, int num,
83  const char *ints, const char *lang, const char *options);
84 
85 /*! \brief Same as \ref ast_say_number() with audiofd for received audio and returns 1 on ctrlfd being readable */
86 SAY_EXTERN int (* ast_say_number_full)(struct ast_channel *chan, int num, const char *ints, const char *lang, const char *options, int audiofd, int ctrlfd) SAY_INIT(ast_say_number_full);
87 
88 /*!
89  * \brief says an enumeration
90  * \param chan channel to say them enumeration on
91  * \param num number to say on the channel
92  * \param ints which dtmf to interrupt on
93  * \param lang language to speak the enumeration
94  * \param options set to 'f' for female, 'm' for male, 'c' for commune, 'n' for neuter
95  * \details
96  * Vocally says an enumeration on a given channel (first, sencond, third, forth, thirtyfirst, hundredth, ....)
97  * Especially useful for dates and messages. Says 'last' if num equals to INT_MAX
98  * \retval 0 on success
99  * \retval DTMF digit on interrupt
100  * \retval -1 on failure
101  */
102 int ast_say_enumeration(struct ast_channel *chan, int num,
103  const char *ints, const char *lang, const char *options);
104 
105 /*! \brief Same as \ref ast_say_enumeration() with audiofd for received audio and returns 1 on ctrlfd being readable */
106 SAY_EXTERN int (* ast_say_enumeration_full)(struct ast_channel *chan, int num, const char *ints, const char *lang, const char *options, int audiofd, int ctrlfd) SAY_INIT(ast_say_enumeration_full);
107 
108 /*!
109  * \brief says digits
110  * \param chan channel to act upon
111  * \param num number to speak
112  * \param ints which dtmf to interrupt on
113  * \param lang language to speak
114  * \details
115  * Vocally says digits of a given number
116  * \retval 0 on success
117  * \retval DTMF if interrupted
118  * \retval -1 on failure
119  */
120 int ast_say_digits(struct ast_channel *chan, int num,
121  const char *ints, const char *lang);
122 
123 /*! \brief Same as \ref ast_say_digits() with audiofd for received audio and returns 1 on ctrlfd being readable */
124 int ast_say_digits_full(struct ast_channel *chan, int num,
125  const char *ints, const char *lang, int audiofd, int ctrlfd);
126 
127 /*!
128  * \brief says digits of a string
129  * \param chan channel to act upon
130  * \param num string to speak
131  * \param ints which dtmf to interrupt on
132  * \param lang language to speak in
133  * \details
134  * Vocally says the digits of a given string
135  * \retval 0 on succes
136  * \retval DTMF if interrupted
137  * \retval -1 on failure
138  */
139 int ast_say_digit_str(struct ast_channel *chan, const char *num,
140  const char *ints, const char *lang);
141 
142 /*! \brief Same as \ref ast_say_digit_str() with audiofd for received audio and returns 1 on ctrlfd being readable */
143 SAY_EXTERN int (* ast_say_digit_str_full)(struct ast_channel *chan, const char *num, const char *ints, const char *lang, int audiofd, int ctrlfd) SAY_INIT(ast_say_digit_str_full);
144 
145 /*! \brief
146  * function to pronounce monetary amounts
147  */
148 int ast_say_money_str(struct ast_channel *chan, const char *num,
149  const char *ints, const char *lang);
150 
151 SAY_EXTERN int (* ast_say_money_str_full)(struct ast_channel *chan, const char *num, const char *ints, const char *lang, int audiofd, int ctrlfd) SAY_INIT(ast_say_money_str_full);
152 
153 /*! \brief
154  * the generic 'say' routine, with the first chars in the string
155  * defining the format to use
156  */
157 SAY_EXTERN int (* ast_say_full)(struct ast_channel *chan, const char *num, const char *ints, const char *lang, const char *options, int audiofd, int ctrlfd) SAY_INIT(ast_say_full);
158 
159 /*!
160  * \brief Controls how ast_say_character_str denotes the case of characters in a string
161  */
163  AST_SAY_CASE_NONE, /*!< Do not distinguish case on any letters */
164  AST_SAY_CASE_LOWER, /*!< Denote case only on lower case letters, upper case is assumed otherwise */
165  AST_SAY_CASE_UPPER, /*!< Denote case only on upper case letters, lower case is assumed otherwise */
166  AST_SAY_CASE_ALL, /*!< Denote case on all letters, upper and lower */
167 };
168 
169 /*! \brief
170  * function to pronounce character and phonetic strings
171  */
172 int ast_say_character_str(struct ast_channel *chan, const char *num,
173  const char *ints, const char *lang, enum ast_say_case_sensitivity sensitivity);
174 
175 SAY_EXTERN int (* ast_say_character_str_full)(struct ast_channel *chan, const char *num, const char *ints, const char *lang, enum ast_say_case_sensitivity sensitivity, int audiofd, int ctrlfd) SAY_INIT(ast_say_character_str_full);
176 
177 int ast_say_phonetic_str(struct ast_channel *chan, const char *num,
178  const char *ints, const char *lang);
179 
180 SAY_EXTERN int (* ast_say_phonetic_str_full)(struct ast_channel *chan, const char *num, const char *ints, const char *lang, int audiofd, int ctrlfd) SAY_INIT(ast_say_phonetic_str_full);
181 
182 SAY_EXTERN int (* ast_say_datetime)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_datetime);
183 SAY_EXTERN int (* ast_say_time)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_time);
184 
185 SAY_EXTERN int (* ast_say_date)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_date);
186 
187 SAY_EXTERN int (* ast_say_datetime_from_now)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_datetime_from_now);
188 
189 SAY_EXTERN int (* ast_say_date_with_format)(struct ast_channel *chan, time_t t, const char *ints, const char *lang, const char *format, const char *timezone) SAY_INIT(ast_say_date_with_format);
190 
191 int ast_say_counted_noun(struct ast_channel *chan, int num, const char *noun);
192 
193 int ast_say_counted_adjective(struct ast_channel *chan, int num, const char *adjective, const char *gender);
194 
195 /*!
196  * \brief Returns an ast_str of files for SayAlpha playback.
197  *
198  * \param str Text to be translated to the corresponding audio files.
199  * \param lang Channel language
200  * \param sensitivity Case sensitivity
201  *
202  * Computes the list of files to be played by SayAlpha.
203  *
204  * \retval ampersand-separated string of Asterisk sound files that can be played back.
205  */
206 struct ast_str* ast_get_character_str(const char *str, const char *lang, enum ast_say_case_sensitivity sensitivity);
207 
208 /*!
209  * \brief Returns an ast_str of files for SayPhonetic playback.
210  *
211  * \param str Text to be translated to the corresponding audio files.
212  * \param lang Channel language
213  *
214  * Computes the list of files to be played by SayPhonetic.
215  *
216  * \retval ampersand-separated string of Asterisk sound files that can be played back.
217  */
218 struct ast_str* ast_get_phonetic_str(const char *str, const char *lang);
219 
220 /*!
221  * \brief Returns an ast_str of files for SayDigits playback.
222  *
223  * \param str Text to be translated to the corresponding audio files.
224  * \param lang Channel language
225  *
226  * Computes the list of files to be played by SayDigits.
227  *
228  * \retval ampersand-separated string of Asterisk sound files that can be played back.
229  */
230 struct ast_str* ast_get_digit_str(const char *str, const char *lang);
231 
232 /*!
233  * \brief Returns an ast_str of files for SayMoney playback.
234  *
235  * \param str Text to be translated to the corresponding audio files.
236  * \param lang Channel language
237  *
238  * Computes the list of files to be played by SayMoney.
239  *
240  * \retval ampersand-separated string of Asterisk sound files that can be played back.
241  */
242 struct ast_str* ast_get_money_str(const char *str, const char *lang);
243 
244 /*!
245  * \brief Returns an ast_str of files for SayNumber playback.
246  *
247  * \param num Integer to be translated to the corresponding audio files.
248  * \param lang Channel language
249  *
250  * Computes the list of files to be played by SayNumber.
251  *
252  * \retval ampersand-separated string of Asterisk sound files that can be played back.
253  */
254 struct ast_str* ast_get_number_str(int num, const char *lang);
255 
256 #if defined(__cplusplus) || defined(c_plusplus)
257 }
258 #endif
259 
260 #endif /* _ASTERISK_SAY_H */
Main Channel structure associated with a channel.
SAY_EXTERN int(* ast_say_number_full)(struct ast_channel *chan, int num, const char *ints, const char *lang, const char *options, int audiofd, int ctrlfd) SAY_INIT(ast_say_number_full)
Same as ast_say_number() with audiofd for received audio and returns 1 on ctrlfd being readable...
Definition: say.h:86
SAY_EXTERN int(* ast_say_time)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_time)
Definition: say.h:183
SAY_EXTERN int(* ast_say_enumeration_full)(struct ast_channel *chan, int num, const char *ints, const char *lang, const char *options, int audiofd, int ctrlfd) SAY_INIT(ast_say_enumeration_full)
Same as ast_say_enumeration() with audiofd for received audio and returns 1 on ctrlfd being readable...
Definition: say.h:106
Time-related functions and macros.
#define LOG_WARNING
Definition: logger.h:274
SAY_EXTERN int(* ast_say_datetime_from_now)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_datetime_from_now)
Definition: say.h:187
int ast_say_digits_full(struct ast_channel *chan, int num, const char *ints, const char *lang, int audiofd, int ctrlfd)
Same as ast_say_digits() with audiofd for received audio and returns 1 on ctrlfd being readable...
Definition: channel.c:8379
struct ast_str * ast_get_number_str(int num, const char *lang)
Returns an ast_str of files for SayNumber playback.
Definition: say.c:525
int ast_say_digit_str(struct ast_channel *chan, const char *num, const char *ints, const char *lang)
says digits of a string
Definition: channel.c:8355
int ast_say_digits(struct ast_channel *chan, int num, const char *ints, const char *lang)
says digits
Definition: channel.c:8349
struct ast_str * ast_get_phonetic_str(const char *str, const char *lang)
Returns an ast_str of files for SayPhonetic playback.
Definition: say.c:195
int ast_say_money_str(struct ast_channel *chan, const char *num, const char *ints, const char *lang)
function to pronounce monetary amounts
Definition: channel.c:8361
const char * str
Definition: app_jack.c:147
Generic File Format Support. Should be included by clients of the file handling routines. File service providers should instead include mod_format.h.
SAY_EXTERN int(* ast_say_money_str_full)(struct ast_channel *chan, const char *num, const char *ints, const char *lang, int audiofd, int ctrlfd) SAY_INIT(ast_say_money_str_full)
Definition: say.h:151
struct ast_str * ast_get_money_str(const char *str, const char *lang)
Returns an ast_str of files for SayMoney playback.
Definition: say.c:419
#define ast_log
Definition: astobj2.c:42
int ast_say_counted_noun(struct ast_channel *chan, int num, const char *noun)
General Asterisk PBX channel definitions.
struct ast_str * ast_get_digit_str(const char *str, const char *lang)
Returns an ast_str of files for SayDigits playback.
Definition: say.c:294
SAY_EXTERN int(* ast_say_digit_str_full)(struct ast_channel *chan, const char *num, const char *ints, const char *lang, int audiofd, int ctrlfd) SAY_INIT(ast_say_digit_str_full)
Same as ast_say_digit_str() with audiofd for received audio and returns 1 on ctrlfd being readable...
Definition: say.h:143
int ast_say_character_str(struct ast_channel *chan, const char *num, const char *ints, const char *lang, enum ast_say_case_sensitivity sensitivity)
function to pronounce character and phonetic strings
Definition: channel.c:8367
SAY_EXTERN int(* ast_say_date)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_date)
Definition: say.h:185
ast_say_case_sensitivity
Controls how ast_say_character_str denotes the case of characters in a string.
Definition: say.h:162
SAY_EXTERN int(* ast_say_date_with_format)(struct ast_channel *chan, time_t t, const char *ints, const char *lang, const char *format, const char *timezone) SAY_INIT(ast_say_date_with_format)
Definition: say.h:189
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:584
#define SAY_INIT(x)
The basic ast_say_* functions are implemented as function pointers, initialized to the function say_s...
Definition: say.h:65
#define SAY_EXTERN
Definition: say.h:66
int ast_say_counted_adjective(struct ast_channel *chan, int num, const char *adjective, const char *gender)
SAY_EXTERN int(* ast_say_datetime)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_datetime)
Definition: say.h:182
struct ast_str * ast_get_character_str(const char *str, const char *lang, enum ast_say_case_sensitivity sensitivity)
Returns an ast_str of files for SayAlpha playback.
Definition: say.c:63
int ast_say_phonetic_str(struct ast_channel *chan, const char *num, const char *ints, const char *lang)
Definition: channel.c:8373
int ast_say_number(struct ast_channel *chan, int num, const char *ints, const char *lang, const char *options)
says a number
Definition: channel.c:8337
SAY_EXTERN int(* ast_say_character_str_full)(struct ast_channel *chan, const char *num, const char *ints, const char *lang, enum ast_say_case_sensitivity sensitivity, int audiofd, int ctrlfd) SAY_INIT(ast_say_character_str_full)
Definition: say.h:175
SAY_EXTERN int(* ast_say_full)(struct ast_channel *chan, const char *num, const char *ints, const char *lang, const char *options, int audiofd, int ctrlfd) SAY_INIT(ast_say_full)
the generic &#39;say&#39; routine, with the first chars in the string defining the format to use ...
Definition: say.h:157
static struct test_options options
int ast_say_enumeration(struct ast_channel *chan, int num, const char *ints, const char *lang, const char *options)
says an enumeration
Definition: channel.c:8343
SAY_EXTERN int(* ast_say_phonetic_str_full)(struct ast_channel *chan, const char *num, const char *ints, const char *lang, int audiofd, int ctrlfd) SAY_INIT(ast_say_phonetic_str_full)
Definition: say.h:180
static snd_pcm_format_t format
Definition: chan_alsa.c:102