Replace ast_say_* functionn with function pointers, so that modules
[asterisk/asterisk.git] / include / asterisk / say.h
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)
32 extern "C" {
33 #endif
34
35 /*! \brief
36  * All ast_say_* functions are implemented as function pointers,
37  * initialized to the function say_stub() which simply returns an error.
38  * An implementation of these functions (e.g. say.c, if available, or
39  * a dynamically loaded module) will just have to reassign the pointers
40  * to the relevant functions to override the previous implementation.
41  * As the conversion from the old implementation of say.c to the new
42  * implementation will be completed, and the API suitably reworked by
43  * removing redundant functions and/or arguments, this mechanism may be
44  * reverted back to pure static functions, if needed.
45  */
46 #if defined(SAY_STUBS)
47 /* provide declarations for the *say*() functions
48  * and initialize them to the stub function
49  */
50 static int say_stub(struct ast_channel *chan, ...)
51 {
52         ast_log(LOG_WARNING, "no implementation for the say() functions\n");
53         return -1;
54 };
55
56 #undef SAY_STUBS
57 #define SAY_INIT(x)      = (typeof (x))say_stub
58 #define SAY_EXTERN
59 #else
60 #define SAY_INIT(x)
61 #define SAY_EXTERN      extern
62 #endif
63
64 /* says a number
65  * \param chan channel to say them number on
66  * \param num number to say on the channel
67  * \param ints which dtmf to interrupt on
68  * \param lang language to speak the number
69  * \param options set to 'f' for female, 'm' for male, 'c' for commune, 'n' for neuter, 'p' for plural
70  * Vocally says a number on a given channel
71  * Returns 0 on success, DTMF digit on interrupt, -1 on failure
72  */
73 SAY_EXTERN int (*ast_say_number)(struct ast_channel *chan, int num, const char *ints, const char *lang, const char *options) SAY_INIT(ast_say_number);
74
75 /* Same as above with audiofd for received audio and returns 1 on ctrlfd being readable */
76 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);
77
78 /* says an enumeration
79  * \param chan channel to say them enumeration on
80  * \param num number to say on the channel
81  * \param ints which dtmf to interrupt on
82  * \param lang language to speak the enumeration
83  * \param options set to 'f' for female, 'm' for male, 'c' for commune, 'n' for neuter, 'p' for plural
84  * Vocally says a enumeration on a given channel (first, sencond, third, forth, thirtyfirst, hundredth, ....) 
85  * especially useful for dates and messages. says 'last' if num equals to INT_MAX
86  * Returns 0 on success, DTMF digit on interrupt, -1 on failure
87  */
88 SAY_EXTERN int (* ast_say_enumeration)(struct ast_channel *chan, int num, const char *ints, const char *lang, const char *options) SAY_INIT(ast_say_enumeration);
89 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);
90
91 /* says digits
92  * \param chan channel to act upon
93  * \param num number to speak
94  * \param ints which dtmf to interrupt on
95  * \param lang language to speak
96  * Vocally says digits of a given number
97  * Returns 0 on success, dtmf if interrupted, -1 on failure
98  */
99 SAY_EXTERN int (*ast_say_digits)(struct ast_channel *chan, int num, const char *ints, const char *lang) SAY_INIT(ast_say_digits);
100 SAY_EXTERN int (*ast_say_digits_full)(struct ast_channel *chan, int num, const char *ints, const char *lang, int audiofd, int ctrlfd) SAY_INIT(ast_say_digits_full);
101
102 /* says digits of a string
103  * \param chan channel to act upon
104  * \param num string to speak
105  * \param ints which dtmf to interrupt on
106  * \param lang language to speak in
107  * Vocally says the digits of a given string
108  * Returns 0 on success, dtmf if interrupted, -1 on failure
109  */
110 SAY_EXTERN int (* ast_say_digit_str)(struct ast_channel *chan, const char *num, const char *ints, const char *lang) SAY_INIT(ast_say_digit_str);
111 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);
112
113 /*
114  * the generic 'say' routine, with the first chars in the string
115  * defining the format to use
116  */
117 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);
118 SAY_EXTERN int (* ast_say_character_str)(struct ast_channel *chan, const char *num, const char *ints, const char *lang) SAY_INIT(ast_say_character_str);
119 SAY_EXTERN int (* ast_say_character_str_full)(struct ast_channel *chan, const char *num, const char *ints, const char *lang, int audiofd, int ctrlfd) SAY_INIT(ast_say_character_str_full);
120 SAY_EXTERN int (* ast_say_phonetic_str)(struct ast_channel *chan, const char *num, const char *ints, const char *lang) SAY_INIT(ast_say_phonetic_str);
121 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);
122
123 SAY_EXTERN int (* ast_say_datetime)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_datetime);
124 SAY_EXTERN int (* ast_say_time)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_time);
125
126 SAY_EXTERN int (* ast_say_date)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_date);
127
128 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);
129
130 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);
131
132 #if defined(__cplusplus) || defined(c_plusplus)
133 }
134 #endif
135
136 #endif /* _ASTERISK_SAY_H */