Wed Oct 28 11:45:42 2009

Asterisk developer's documentation


say.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2005, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Say numbers and dates (maybe words one day too)
00021  */
00022 
00023 #ifndef _ASTERISK_SAY_H
00024 #define _ASTERISK_SAY_H
00025 
00026 #include "asterisk/channel.h"
00027 #include "asterisk/file.h"
00028 
00029 #include <time.h>
00030 
00031 #if defined(__cplusplus) || defined(c_plusplus)
00032 extern "C" {
00033 #endif
00034 
00035 /*! \brief
00036  * The basic ast_say_* functions are implemented as function pointers,
00037  * initialized to the function say_stub() which simply returns an error.
00038  * Other interfaces, declared here as regular functions, are simply
00039  * wrappers around the basic functions.
00040  *
00041  * An implementation of the basic ast_say functions (e.g. from say.c or from
00042  * a dynamically loaded module) will just have to reassign the pointers
00043  * to the relevant functions to override the previous implementation.
00044  *
00045  * \todo XXX
00046  * As the conversion from the old implementation of say.c to the new
00047  * implementation will be completed, and the API suitably reworked by
00048  * removing redundant functions and/or arguments, this mechanism may be
00049  * reverted back to pure static functions, if needed.
00050  */
00051 #if defined(SAY_STUBS)
00052 /* provide declarations for the *say*() functions
00053  * and initialize them to the stub function
00054  */
00055 static int say_stub(struct ast_channel *chan, ...)
00056 {
00057    ast_log(LOG_WARNING, "no implementation for the say() functions\n");
00058         return -1;
00059 };
00060 
00061 #undef SAY_STUBS
00062 #define  SAY_INIT(x)  = (typeof (x))say_stub
00063 #define  SAY_EXTERN
00064 #else
00065 #define SAY_INIT(x)
00066 #define  SAY_EXTERN  extern
00067 #endif
00068 
00069 /* 
00070  * \brief says a number
00071  * \param chan channel to say them number on
00072  * \param num number to say on the channel
00073  * \param ints which dtmf to interrupt on
00074  * \param lang language to speak the number
00075  * \param options set to 'f' for female, 'm' for male, 'c' for commune, 'n' for neuter, 'p' for plural
00076  * Vocally says a number on a given channel
00077  * \retval 0 on success
00078  * \retval DTMF digit on interrupt
00079  * \retval -1 on failure
00080  */
00081 int ast_say_number(struct ast_channel *chan, int num,
00082    const char *ints, const char *lang, const char *options);
00083 
00084 /* Same as above with audiofd for received audio and returns 1 on ctrlfd being readable */
00085 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);
00086 
00087 /* 
00088  * \brief says an enumeration
00089  * \param chan channel to say them enumeration on
00090  * \param num number to say on the channel
00091  * \param ints which dtmf to interrupt on
00092  * \param lang language to speak the enumeration
00093  * \param options set to 'f' for female, 'm' for male, 'c' for commune, 'n' for neuter, 'p' for plural
00094  * Vocally says a enumeration on a given channel (first, sencond, third, forth, thirtyfirst, hundredth, ....) 
00095  * especially useful for dates and messages. says 'last' if num equals to INT_MAX
00096  * \retval 0 on success
00097  * \retval DTMF digit on interrupt
00098  * \retval -1 on failure
00099  */
00100 int ast_say_enumeration(struct ast_channel *chan, int num,
00101    const char *ints, const char *lang, const char *options);
00102 
00103 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);
00104 
00105 /* 
00106  * \brief says digits
00107  * \param chan channel to act upon
00108  * \param num number to speak
00109  * \param ints which dtmf to interrupt on
00110  * \param lang language to speak
00111  * Vocally says digits of a given number
00112  * \retval 0 on success
00113  * \retval DTMF if interrupted
00114  * \retval -1 on failure
00115  */
00116 int ast_say_digits(struct ast_channel *chan, int num,
00117    const char *ints, const char *lang);
00118 
00119 int ast_say_digits_full(struct ast_channel *chan, int num,
00120    const char *ints, const char *lang, int audiofd, int ctrlfd);
00121 
00122 /* 
00123  * \brief says digits of a string
00124  * \param chan channel to act upon
00125  * \param num string to speak
00126  * \param ints which dtmf to interrupt on
00127  * \param lang language to speak in
00128  * Vocally says the digits of a given string
00129  * \retval 0 on succes
00130  * \retval DTMF if interrupted
00131  * \retval -1 on failure
00132  */
00133 int ast_say_digit_str(struct ast_channel *chan, const char *num,
00134    const char *ints, const char *lang);
00135 
00136 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);
00137 
00138 /*
00139  * the generic 'say' routine, with the first chars in the string
00140  * defining the format to use
00141  */
00142 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);
00143 
00144 /*
00145  * other function to pronounce character and phonetic strings
00146  */
00147 int ast_say_character_str(struct ast_channel *chan, const char *num,
00148    const char *ints, const char *lang);
00149 
00150 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);
00151 
00152 int ast_say_phonetic_str(struct ast_channel *chan, const char *num,
00153    const char *ints, const char *lang);
00154 
00155 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);
00156 
00157 SAY_EXTERN int (* ast_say_datetime)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_datetime);
00158 SAY_EXTERN int (* ast_say_time)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_time);
00159 
00160 SAY_EXTERN int (* ast_say_date)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_date);
00161 
00162 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);
00163 
00164 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);
00165 
00166 int ast_say_counted_noun(struct ast_channel *chan, int num, const char *noun);
00167 
00168 int ast_say_counted_adjective(struct ast_channel *chan, int num, const char *adjective, const char *gender);
00169 
00170 #if defined(__cplusplus) || defined(c_plusplus)
00171 }
00172 #endif
00173 
00174 #endif /* _ASTERISK_SAY_H */

Generated on Wed Oct 28 11:45:42 2009 for Asterisk - the Open Source PBX by  doxygen 1.5.6