Merged revisions 47352 via svnmerge from
[asterisk/asterisk.git] / res / res_speech.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2006, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@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  *
21  * \brief Generic Speech Recognition API
22  *
23  * \author Joshua Colp <jcolp@digium.com>
24  */
25
26 #include "asterisk.h"
27
28 ASTERISK_FILE_VERSION(__FILE__, "$Revision$");
29
30 #include <stdio.h>
31 #include <stdlib.h>
32 #include <unistd.h>
33 #include <string.h>
34
35 #include "asterisk/channel.h"
36 #include "asterisk/module.h"
37 #include "asterisk/lock.h"
38 #include "asterisk/linkedlists.h"
39 #include "asterisk/cli.h"
40 #include "asterisk/term.h"
41 #include "asterisk/options.h"
42 #include "asterisk/speech.h"
43
44
45 static AST_LIST_HEAD_STATIC(engines, ast_speech_engine);
46 static struct ast_speech_engine *default_engine = NULL;
47
48 /*! \brief Find a speech recognition engine of specified name, if NULL then use the default one */
49 static struct ast_speech_engine *find_engine(char *engine_name)
50 {
51         struct ast_speech_engine *engine = NULL;
52
53         /* If no name is specified -- use the default engine */
54         if (engine_name == NULL || strlen(engine_name) == 0) {
55                 return default_engine;
56         }
57
58         AST_LIST_LOCK(&engines);
59         AST_LIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
60                 if (!strcasecmp(engine->name, engine_name)) {
61                         break;
62                 }
63         }
64         AST_LIST_TRAVERSE_SAFE_END
65         AST_LIST_UNLOCK(&engines);
66
67         return engine;
68 }
69
70 /*! \brief Activate a loaded (either local or global) grammar */
71 int ast_speech_grammar_activate(struct ast_speech *speech, char *grammar_name)
72 {
73         int res = 0;
74
75         if (speech->engine->activate != NULL) {
76                 res = speech->engine->activate(speech, grammar_name);
77         }
78
79         return res;
80 }
81
82 /*! \brief Deactivate a loaded grammar on a speech structure */
83 int ast_speech_grammar_deactivate(struct ast_speech *speech, char *grammar_name)
84 {
85         int res = 0;
86
87         if (speech->engine->deactivate != NULL) {
88                 res = speech->engine->deactivate(speech, grammar_name);
89         }
90
91         return res;
92 }
93
94 /*! \brief Load a local grammar on a speech structure */
95 int ast_speech_grammar_load(struct ast_speech *speech, char *grammar_name, char *grammar)
96 {
97         int res = 0;
98
99         if (speech->engine->load != NULL) {
100                 res = speech->engine->load(speech, grammar_name, grammar);
101         }
102
103         return res;
104 }
105
106 /*! \brief Unload a local grammar from a speech structure */
107 int ast_speech_grammar_unload(struct ast_speech *speech, char *grammar_name)
108 {
109         int res = 0;
110
111         if (speech->engine->unload != NULL) {
112                 res = speech->engine->unload(speech, grammar_name);
113         }
114
115         return res;
116 }
117
118 /*! \brief Return the results of a recognition from the speech structure */
119 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech)
120 {
121         struct ast_speech_result *result = NULL;
122
123         if (speech->engine->get != NULL) {
124                 result = speech->engine->get(speech);
125         }
126
127         return result;
128 }
129
130 /*! \brief Free a list of results */
131 int ast_speech_results_free(struct ast_speech_result *result)
132 {
133         struct ast_speech_result *current_result = result, *prev_result = NULL;
134         int res = 0;
135
136         while (current_result != NULL) {
137                 prev_result = current_result;
138                 /* Deallocate what we can */
139                 if (current_result->text != NULL) {
140                         free(current_result->text);
141                         current_result->text = NULL;
142                 }
143                 if (current_result->grammar != NULL) {
144                         free(current_result->grammar);
145                         current_result->grammar = NULL;
146                 }
147                 /* Move on and then free ourselves */
148                 current_result = current_result->next;
149                 free(prev_result);
150                 prev_result = NULL;
151         }
152
153         return res;
154 }
155
156 /*! \brief Start speech recognition on a speech structure */
157 void ast_speech_start(struct ast_speech *speech)
158 {
159
160         /* Clear any flags that may affect things */
161         ast_clear_flag(speech, AST_SPEECH_SPOKE);
162         ast_clear_flag(speech, AST_SPEECH_QUIET);
163
164         /* If results are on the structure, free them since we are starting again */
165         if (speech->results != NULL) {
166                 ast_speech_results_free(speech->results);
167                 speech->results = NULL;
168         }
169
170         /* If the engine needs to start stuff up, do it */
171         if (speech->engine->start != NULL) {
172                 speech->engine->start(speech);
173         }
174
175         return;
176 }
177
178 /*! \brief Write in signed linear audio to be recognized */
179 int ast_speech_write(struct ast_speech *speech, void *data, int len)
180 {
181         int res = 0;
182
183         /* Make sure the speech engine is ready to accept audio */
184         if (speech->state != AST_SPEECH_STATE_READY) {
185                 return -1;
186         }
187
188         if (speech->engine->write != NULL) {
189                 speech->engine->write(speech, data, len);
190         }
191
192         return res;
193 }
194
195 /*! \brief Change an engine specific attribute */
196 int ast_speech_change(struct ast_speech *speech, char *name, const char *value)
197 {
198         int res = 0;
199
200         if (speech->engine->change != NULL) {
201                 res = speech->engine->change(speech, name, value);
202         }
203
204         return res;
205 }
206
207 /*! \brief Create a new speech structure using the engine specified */
208 struct ast_speech *ast_speech_new(char *engine_name, int format)
209 {
210         struct ast_speech_engine *engine = NULL;
211         struct ast_speech *new_speech = NULL;
212
213         /* Try to find the speech recognition engine that was requested */
214         engine = find_engine(engine_name);
215         if (engine == NULL) {
216                 /* Invalid engine or no engine available */
217                 return NULL;
218         }
219
220         /* Allocate our own speech structure, and try to allocate a structure from the engine too */
221         new_speech = ast_calloc(1, sizeof(*new_speech));
222         if (new_speech == NULL) {
223                 /* Ran out of memory while trying to allocate some for a speech structure */
224                 return NULL;
225         }
226
227         /* Initialize the lock */
228         ast_mutex_init(&new_speech->lock);
229
230         /* Make sure no results are present */
231         new_speech->results = NULL;
232
233         /* Copy over our engine pointer */
234         new_speech->engine = engine;
235
236         /* We are not ready to accept audio yet */
237         ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
238
239         /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
240         if (engine->new(new_speech)) {
241                 ast_mutex_destroy(&new_speech->lock);
242                 free(new_speech);
243                 new_speech = NULL;
244         }
245
246         return new_speech;
247 }
248
249 /*! \brief Destroy a speech structure */
250 int ast_speech_destroy(struct ast_speech *speech)
251 {
252         int res = 0;
253
254         /* Call our engine so we are destroyed properly */
255         speech->engine->destroy(speech);
256
257         /* Deinitialize the lock */
258         ast_mutex_destroy(&speech->lock);
259
260         /* If results exist on the speech structure, destroy them */
261         if (speech->results != NULL) {
262                 ast_speech_results_free(speech->results);
263                 speech->results = NULL;
264         }
265
266         /* If a processing sound is set - free the memory used by it */
267         if (speech->processing_sound != NULL) {
268                 free(speech->processing_sound);
269                 speech->processing_sound = NULL;
270         }
271
272         /* Aloha we are done */
273         free(speech);
274         speech = NULL;
275
276         return res;
277 }
278
279 /*! \brief Change state of a speech structure */
280 int ast_speech_change_state(struct ast_speech *speech, int state)
281 {
282         int res = 0;
283
284         switch (state) {
285         case AST_SPEECH_STATE_WAIT:
286                 /* The engine heard audio, so they spoke */
287                 ast_set_flag(speech, AST_SPEECH_SPOKE);
288         default:
289                 speech->state = state;
290                 break;
291         }
292
293         return res;
294 }
295
296 /*! \brief Register a speech recognition engine */
297 int ast_speech_register(struct ast_speech_engine *engine)
298 {
299         struct ast_speech_engine *existing_engine = NULL;
300         int res = 0;
301
302         existing_engine = find_engine(engine->name);
303         if (existing_engine != NULL) {
304                 /* Engine already loaded */
305                 return -1;
306         }
307
308         if (option_verbose > 1)
309                 ast_verbose(VERBOSE_PREFIX_2 "Registered speech recognition engine '%s'\n", engine->name);
310
311         /* Add to the engine linked list and make default if needed */
312         AST_LIST_LOCK(&engines);
313         AST_LIST_INSERT_HEAD(&engines, engine, list);
314         if (default_engine == NULL) {
315                 default_engine = engine;
316                 if (option_verbose > 1)
317                         ast_verbose(VERBOSE_PREFIX_2 "Made '%s' the default speech recognition engine\n", engine->name);
318         }
319         AST_LIST_UNLOCK(&engines);
320
321         return res;
322 }
323
324 /*! \brief Unregister a speech recognition engine */
325 int ast_speech_unregister(char *engine_name)
326 {
327         struct ast_speech_engine *engine = NULL;
328         int res = -1;
329
330         if (engine_name == NULL) {
331                 return res;
332         }
333
334         AST_LIST_LOCK(&engines);
335         AST_LIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
336                 if (!strcasecmp(engine->name, engine_name)) {
337                         /* We have our engine... removed it */
338                         AST_LIST_REMOVE_CURRENT(&engines, list);
339                         /* If this was the default engine, we need to pick a new one */
340                         if (default_engine == engine) {
341                                 default_engine = AST_LIST_FIRST(&engines);
342                         }
343                         if (option_verbose > 1)
344                                 ast_verbose(VERBOSE_PREFIX_2 "Unregistered speech recognition engine '%s'\n", engine_name);
345                         /* All went well */
346                         res = 0;
347                         break;
348                 }
349         }
350         AST_LIST_TRAVERSE_SAFE_END
351         AST_LIST_UNLOCK(&engines);
352
353         return res;
354 }
355
356 static int unload_module(void)
357 {
358         /* We can not be unloaded */
359         return -1;
360 }
361
362 static int load_module(void)
363 {
364         int res = 0;
365
366         /* Initialize our list of engines */
367         AST_LIST_HEAD_INIT_NOLOCK(&engines);
368
369         return res;
370 }
371
372 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS, "Generic Speech Recognition API",
373                 .load = load_module,
374                 .unload = unload_module,
375                 );