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 */