Merge "res_musiconhold: Start playlist after initial announcement"
[asterisk/asterisk.git] / apps / app_saycounted.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2008, Trinity College Computing Center
5  * Written by David Chappell
6  *
7  * See http://www.asterisk.org for more information about
8  * the Asterisk project. Please do not directly contact
9  * any of the maintainers of this project for assistance;
10  * the project provides a web site, mailing lists and IRC
11  * channels for your use.
12  *
13  * This program is free software, distributed under the terms of
14  * the GNU General Public License Version 2. See the LICENSE file
15  * at the top of the source tree.
16  */
17
18 /*! \file
19  *
20  * \brief Applications to decline words according to current language
21  *
22  * \author David Chappell <David.Chappell@trincoll.edu>
23  *
24  * \ingroup applications
25  */
26
27 /*** MODULEINFO
28         <defaultenabled>no</defaultenabled>
29         <support_level>extended</support_level>
30  ***/
31
32 /*** DOCUMENTATION
33         <application name="SayCountedNoun" language="en_US">
34                 <synopsis>
35                         Say a noun in declined form in order to count things
36                 </synopsis>
37                 <syntax>
38                         <parameter name="number" required="true">
39                                 <para>The number of things</para>
40                         </parameter>
41                         <parameter name="filename" required="true">
42                                 <para>File name stem for the noun that is the the name of the things</para>
43                         </parameter>
44                 </syntax>
45                 <description>
46                         <para>Selects and plays the proper singular or plural form of a noun
47                         when saying things such as "five calls".  English has simple rules
48                         for deciding when to say "call" and when to say "calls", but other
49                         languages have complicated rules which would be extremely difficult
50                         to implement in the Asterisk dialplan language.</para>
51                         <para>The correct sound file is selected by examining the
52                         <replaceable>number</replaceable> and adding the appropriate suffix
53                         to <replaceable>filename</replaceable>. If the channel language is
54                         English, then the suffix will be either empty or "s". If the channel
55                         language is Russian or some other Slavic language, then the suffix
56                         will be empty for nominative, "x1" for genative singular, and "x2"
57                         for genative plural.</para>
58                         <para>Note that combining <replaceable>filename</replaceable> with
59                         a suffix will not necessarily produce a correctly spelled plural
60                         form. For example, SayCountedNoun(2,man) will play the sound file
61                         "mans" rather than "men". This behavior is intentional. Since the
62                         file name is never seen by the end user, there is no need to
63                         implement complicated spelling rules.  We simply record the word
64                         "men" in the sound file named "mans".</para>
65                         <para>This application does not automatically answer and should be
66                         preceeded by an application such as Answer() or Progress.</para>
67                 </description>
68                 <see-also>
69                         <ref type="application">SayCountedAdj</ref>
70                         <ref type="application">SayNumber</ref>
71                 </see-also>
72         </application>
73         <application name="SayCountedAdj" language="en_US">
74                 <synopsis>
75                         Say a adjective in declined form in order to count things
76                 </synopsis>
77                 <syntax>
78                         <parameter name="number" required="true">
79                                 <para>The number of things</para>
80                         </parameter>
81                         <parameter name="filename" required="true">
82                                 <para>File name stem for the adjective</para>
83                         </parameter>
84                         <parameter name="gender">
85                                 <para>The gender of the noun modified, one of 'm', 'f', 'n', or 'c'</para>
86                         </parameter>
87                 </syntax>
88                 <description>
89                         <para>Selects and plays the proper form of an adjective according to
90                         the gender and of the noun which it modifies and the number of
91                         objects named by the noun-verb combination which have been counted.
92                         Used when saying things such as "5 new messages".  The various
93                         singular and plural forms of the adjective are selected by adding
94                         suffixes to <replaceable>filename</replaceable>.</para>
95                         <para>If the channel language is English, then no suffix will ever
96                         be added (since, in English, adjectives are not declined). If the
97                         channel language is Russian or some other slavic language, then the
98                         suffix will the specified <replaceable>gender</replaceable> for
99                         nominative, and "x" for genative plural. (The genative singular is
100                         not used when counting things.) For example, SayCountedAdj(1,new,f)
101                         will play sound file "newa" (containing the word "novaya"), but
102                         SayCountedAdj(5,new,f) will play sound file "newx" (containing the
103                         word "novikh").</para>
104                         <para>This application does not automatically answer and should be
105                         preceeded by an application such as Answer(), Progress(), or
106                         Proceeding().</para>
107                 </description>
108                 <see-also>
109                         <ref type="application">SayCountedNoun</ref>
110                         <ref type="application">SayNumber</ref>
111                 </see-also>
112         </application>
113  ***/
114
115 #include "asterisk.h"
116
117 #include "asterisk/logger.h"
118 #include "asterisk/module.h"
119 #include "asterisk/app.h"
120 #include "asterisk/say.h"
121
122 static int saycountednoun_exec(struct ast_channel *chan, const char *data)
123 {
124         char *parse;
125         int number;
126         AST_DECLARE_APP_ARGS(args,
127                 AST_APP_ARG(number);
128                 AST_APP_ARG(noun);
129         );
130
131         if (ast_strlen_zero(data)) {
132                 ast_log(LOG_WARNING, "SayCountedNoun requires two arguments (<number>,<noun>)\n");
133                 return -1;
134         }
135
136         parse = ast_strdupa(data);
137         AST_STANDARD_APP_ARGS(args, parse);
138
139         if (args.argc != 2) {
140                 ast_log(LOG_WARNING, "SayCountedNoun requires two arguments\n");
141                 return -1;
142         }
143
144         if (sscanf(args.number, "%d", &number) != 1) {
145                 ast_log(LOG_WARNING, "First argument must be a number between 0 and 2,147,483,647.\n");
146                 return -1;
147         }
148
149         return ast_say_counted_noun(chan, number, args.noun);
150 }
151
152 static int saycountedadj_exec(struct ast_channel *chan, const char *data)
153 {
154         char *parse;
155         int number;
156         AST_DECLARE_APP_ARGS(args,
157                 AST_APP_ARG(number);
158                 AST_APP_ARG(adjective);
159                 AST_APP_ARG(gender);
160         );
161
162         if (ast_strlen_zero(data)) {
163                 ast_log(LOG_WARNING, "SayCountedAdj requires two or three arguments (<number>,<adjective>[,<gender>])\n");
164                 return -1;
165         }
166
167         parse = ast_strdupa(data);
168         AST_STANDARD_APP_ARGS(args, parse);
169
170         if (args.argc < 2) {
171                 ast_log(LOG_WARNING, "SayCountedAdj requires at least two arguments\n");
172                 return -1;
173         }
174
175         if (sscanf(args.number, "%d", &number) != 1) {
176                 ast_log(LOG_WARNING, "First argument must be a number between 0 and 2,147,483,647.\n");
177                 return -1;
178         }
179
180         if (!ast_strlen_zero(args.gender)) {
181                 if (strchr("cCfFmMnN", args.gender[0])) {
182                         ast_log(LOG_WARNING, "SayCountedAdj gender option must be one of 'f', 'm', 'c', or 'n'.\n");
183                         return -1;
184                 }
185         }
186
187         return ast_say_counted_adjective(chan, number, args.adjective, args.gender);
188 }
189
190 static int load_module(void)
191 {
192         int res;
193         res = ast_register_application_xml("SayCountedNoun", saycountednoun_exec);
194         res |= ast_register_application_xml("SayCountedAdj", saycountedadj_exec);
195         return res;
196 }
197
198 static int unload_module(void)
199 {
200         int res;
201         res = ast_unregister_application("SayCountedNoun");
202         res |= ast_unregister_application("SayCountedAdj");
203         return res;
204 }
205
206 AST_MODULE_INFO_STANDARD_EXTENDED(ASTERISK_GPL_KEY, "Decline words according to channel language");
207