Asterisk - The Open Source Telephony Project GIT-master-55f4e6d
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 <markster@digium.com>
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)
32extern "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 */
55static 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 */
82int 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 */
86SAY_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 ordinal number
90 * \param chan channel to say them number on
91 * \param num ordinal number to say on the channel
92 * \param ints which dtmf to interrupt on
93 * \param lang language to speak the number
94 * \param options set to 'f' for female, 'm' for male, 'c' for commune, 'n' for neuter
95 * \details
96 * Vocally says an ordinal number on a given channel
97 * \retval 0 on success
98 * \retval DTMF digit on interrupt
99 * \retval -1 on failure
100 */
101int ast_say_ordinal(struct ast_channel *chan, int num,
102 const char *ints, const char *lang, const char *options);
103
104/*! \brief Same as \ref ast_say_number() with audiofd for received audio and returns 1 on ctrlfd being readable */
105SAY_EXTERN int (* ast_say_ordinal_full)(struct ast_channel *chan, int num, const char *ints, const char *lang, const char *options, int audiofd, int ctrlfd) SAY_INIT(ast_say_ordinal_full);
106
107/*!
108 * \brief says an enumeration
109 * \param chan channel to say them enumeration on
110 * \param num number to say on the channel
111 * \param ints which dtmf to interrupt on
112 * \param lang language to speak the enumeration
113 * \param options set to 'f' for female, 'm' for male, 'c' for commune, 'n' for neuter
114 * \details
115 * Vocally says an enumeration on a given channel (first, second, third, forth, thirtyfirst, hundredth, ....)
116 * Especially useful for dates and messages. Says 'last' if num equals to INT_MAX
117 * \retval 0 on success
118 * \retval DTMF digit on interrupt
119 * \retval -1 on failure
120 */
121int ast_say_enumeration(struct ast_channel *chan, int num,
122 const char *ints, const char *lang, const char *options);
123
124/*! \brief Same as \ref ast_say_enumeration() with audiofd for received audio and returns 1 on ctrlfd being readable */
125SAY_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);
126
127/*!
128 * \brief says digits
129 * \param chan channel to act upon
130 * \param num number to speak
131 * \param ints which dtmf to interrupt on
132 * \param lang language to speak
133 * \details
134 * Vocally says digits of a given number
135 * \retval 0 on success
136 * \retval DTMF if interrupted
137 * \retval -1 on failure
138 */
139int ast_say_digits(struct ast_channel *chan, int num,
140 const char *ints, const char *lang);
141
142/*! \brief Same as \ref ast_say_digits() with audiofd for received audio and returns 1 on ctrlfd being readable */
143int ast_say_digits_full(struct ast_channel *chan, int num,
144 const char *ints, const char *lang, int audiofd, int ctrlfd);
145
146/*!
147 * \brief says digits of a string
148 * \param chan channel to act upon
149 * \param num string to speak
150 * \param ints which dtmf to interrupt on
151 * \param lang language to speak in
152 * \details
153 * Vocally says the digits of a given string
154 * \retval 0 on succes
155 * \retval DTMF if interrupted
156 * \retval -1 on failure
157 */
158int ast_say_digit_str(struct ast_channel *chan, const char *num,
159 const char *ints, const char *lang);
160
161/*! \brief Same as \ref ast_say_digit_str() with audiofd for received audio and returns 1 on ctrlfd being readable */
162SAY_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);
163
164/*! \brief
165 * function to pronounce monetary amounts
166 */
167int ast_say_money_str(struct ast_channel *chan, const char *num,
168 const char *ints, const char *lang);
169
170SAY_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);
171
172/*! \brief
173 * the generic 'say' routine, with the first chars in the string
174 * defining the format to use
175 */
176SAY_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);
177
178/*!
179 * \brief Controls how ast_say_character_str denotes the case of characters in a string
180 */
182 AST_SAY_CASE_NONE, /*!< Do not distinguish case on any letters */
183 AST_SAY_CASE_LOWER, /*!< Denote case only on lower case letters, upper case is assumed otherwise */
184 AST_SAY_CASE_UPPER, /*!< Denote case only on upper case letters, lower case is assumed otherwise */
185 AST_SAY_CASE_ALL, /*!< Denote case on all letters, upper and lower */
186};
187
188/*! \brief
189 * function to pronounce character and phonetic strings
190 */
191int ast_say_character_str(struct ast_channel *chan, const char *num,
192 const char *ints, const char *lang, enum ast_say_case_sensitivity sensitivity);
193
194SAY_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);
195
196int ast_say_phonetic_str(struct ast_channel *chan, const char *num,
197 const char *ints, const char *lang);
198
199SAY_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);
200
201SAY_EXTERN int (* ast_say_datetime)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_datetime);
202SAY_EXTERN int (* ast_say_time)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_time);
203
204SAY_EXTERN int (* ast_say_date)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_date);
205
206SAY_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);
207
208SAY_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);
209
210int ast_say_counted_noun(struct ast_channel *chan, int num, const char *noun);
211
212int ast_say_counted_adjective(struct ast_channel *chan, int num, const char *adjective, const char *gender);
213
214/*!
215 * \brief Returns an ast_str of files for SayAlpha playback.
216 *
217 * \param str Text to be translated to the corresponding audio files.
218 * \param lang Channel language
219 * \param sensitivity Case sensitivity
220 *
221 * Computes the list of files to be played by SayAlpha.
222 *
223 * \retval ampersand-separated string of Asterisk sound files that can be played back.
224 */
225struct ast_str* ast_get_character_str(const char *str, const char *lang, enum ast_say_case_sensitivity sensitivity);
226
227/*!
228 * \brief Returns an ast_str of files for SayPhonetic playback.
229 *
230 * \param str Text to be translated to the corresponding audio files.
231 * \param lang Channel language
232 *
233 * Computes the list of files to be played by SayPhonetic.
234 *
235 * \retval ampersand-separated string of Asterisk sound files that can be played back.
236 */
237struct ast_str* ast_get_phonetic_str(const char *str, const char *lang);
238
239/*!
240 * \brief Returns an ast_str of files for SayDigits playback.
241 *
242 * \param str Text to be translated to the corresponding audio files.
243 * \param lang Channel language
244 *
245 * Computes the list of files to be played by SayDigits.
246 *
247 * \retval ampersand-separated string of Asterisk sound files that can be played back.
248 */
249struct ast_str* ast_get_digit_str(const char *str, const char *lang);
250
251/*!
252 * \brief Returns an ast_str of files for SayMoney playback.
253 *
254 * \param str Text to be translated to the corresponding audio files.
255 * \param lang Channel language
256 *
257 * Computes the list of files to be played by SayMoney.
258 *
259 * \retval ampersand-separated string of Asterisk sound files that can be played back.
260 */
261struct ast_str* ast_get_money_str(const char *str, const char *lang);
262
263/*!
264 * \brief Returns an ast_str of files for SayNumber playback.
265 *
266 * \param num Integer to be translated to the corresponding audio files.
267 * \param lang Channel language
268 *
269 * Computes the list of files to be played by SayNumber.
270 *
271 * \retval ampersand-separated string of Asterisk sound files that can be played back.
272 */
273struct ast_str* ast_get_number_str(int num, const char *lang);
274
275/*!
276 * \brief Returns an ast_str of files for SayOrdinal playback.
277 *
278 * \param num Integer to be translated to the corresponding audio files.
279 * \param lang Channel language
280 *
281 * Computes the list of files to be played by SayOrdinal.
282 *
283 * \retval ampersand-separated string of Asterisk sound files that can be played back.
284 */
285struct ast_str* ast_get_ordinal_str(int num, const char *lang);
286
287#if defined(__cplusplus) || defined(c_plusplus)
288}
289#endif
290
291#endif /* _ASTERISK_SAY_H */
const char * str
Definition: app_jack.c:147
#define ast_log
Definition: astobj2.c:42
General Asterisk PBX channel definitions.
Generic File Format Support. Should be included by clients of the file handling routines....
#define LOG_WARNING
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:170
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:206
struct ast_str * ast_get_ordinal_str(int num, const char *lang)
Returns an ast_str of files for SayOrdinal playback.
Definition: say.c:686
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:8265
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:204
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_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:125
int ast_say_phonetic_str(struct ast_channel *chan, const char *num, const char *ints, const char *lang)
Definition: channel.c:8277
int ast_say_ordinal(struct ast_channel *chan, int num, const char *ints, const char *lang, const char *options)
says an ordinal number
Definition: channel.c:8241
SAY_EXTERN int(* ast_say_ordinal_full)(struct ast_channel *chan, int num, const char *ints, const char *lang, const char *options, int audiofd, int ctrlfd) SAY_INIT(ast_say_ordinal_full)
Same as ast_say_number() with audiofd for received audio and returns 1 on ctrlfd being readable.
Definition: say.h:105
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:8271
#define SAY_EXTERN
Definition: say.h:66
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:194
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 'say' routine, with the first chars in the string defining the format to use
Definition: say.h:176
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:64
int ast_say_digits(struct ast_channel *chan, int num, const char *ints, const char *lang)
says digits
Definition: channel.c:8253
struct ast_str * ast_get_number_str(int num, const char *lang)
Returns an ast_str of files for SayNumber playback.
Definition: say.c:566
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:8235
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:216
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:208
int ast_say_counted_noun(struct ast_channel *chan, int num, const char *noun)
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:449
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:162
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:8247
ast_say_case_sensitivity
Controls how ast_say_character_str denotes the case of characters in a string.
Definition: say.h:181
@ AST_SAY_CASE_LOWER
Definition: say.h:183
@ AST_SAY_CASE_ALL
Definition: say.h:185
@ AST_SAY_CASE_UPPER
Definition: say.h:184
@ AST_SAY_CASE_NONE
Definition: say.h:182
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:8283
int ast_say_counted_adjective(struct ast_channel *chan, int num, const char *adjective, const char *gender)
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:202
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:8259
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:199
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:300
#define SAY_INIT(x)
The basic ast_say_* functions are implemented as function pointers, initialized to the function say_s...
Definition: say.h:65
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:201
Main Channel structure associated with a channel.
Support for dynamic strings.
Definition: strings.h:623
static struct test_options options
Time-related functions and macros.