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  * 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, 'p' for plural
  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, 'p' for plural
  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  * the generic 'say' routine, with the first chars in the string
 147  * defining the format to use
 148  */
 149 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);
 150
 151 /*! \brief
 152  * function to pronounce character and phonetic strings
 153  */
 154 int ast_say_character_str(struct ast_channel *chan, const char *num,
 155         const char *ints, const char *lang);
 156
 157 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);
 158
 159 int ast_say_phonetic_str(struct ast_channel *chan, const char *num,
 160         const char *ints, const char *lang);
 161
 162 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);
 163
 164 SAY_EXTERN int (* ast_say_datetime)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_datetime);
 165 SAY_EXTERN int (* ast_say_time)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_time);
 166
 167 SAY_EXTERN int (* ast_say_date)(struct ast_channel *chan, time_t t, const char *ints, const char *lang) SAY_INIT(ast_say_date);
 168
 169 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);
 170
 171 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);
 172
 173 int ast_say_counted_noun(struct ast_channel *chan, int num, const char *noun);
 174
 175 int ast_say_counted_adjective(struct ast_channel *chan, int num, const char *adjective, const char *gender);
 176
 177 #if defined(__cplusplus) || defined(c_plusplus)
 178 }
 179 #endif
 180
 181 #endif /* _ASTERISK_SAY_H */