Revert an errant part of a previous cleanup, to fix a memory corruption issue.
[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 "asterisk/channel.h"
31 #include "asterisk/module.h"
32 #include "asterisk/lock.h"
33 #include "asterisk/linkedlists.h"
34 #include "asterisk/cli.h"
35 #include "asterisk/term.h"
36 #include "asterisk/speech.h"
37
38
39 static AST_RWLIST_HEAD_STATIC(engines, ast_speech_engine);
40 static struct ast_speech_engine *default_engine = NULL;
41
42 /*! \brief Find a speech recognition engine of specified name, if NULL then use the default one */
43 static struct ast_speech_engine *find_engine(const char *engine_name)
44 {
45         struct ast_speech_engine *engine = NULL;
46
47         /* If no name is specified -- use the default engine */
48         if (ast_strlen_zero(engine_name))
49                 return default_engine;
50
51         AST_RWLIST_RDLOCK(&engines);
52         AST_RWLIST_TRAVERSE(&engines, engine, list) {
53                 if (!strcasecmp(engine->name, engine_name)) {
54                         break;
55                 }
56         }
57         AST_RWLIST_UNLOCK(&engines);
58
59         return engine;
60 }
61
62 /*! \brief Activate a loaded (either local or global) grammar */
63 int ast_speech_grammar_activate(struct ast_speech *speech, const char *grammar_name)
64 {
65         return (speech->engine->activate ? speech->engine->activate(speech, grammar_name) : -1);
66 }
67
68 /*! \brief Deactivate a loaded grammar on a speech structure */
69 int ast_speech_grammar_deactivate(struct ast_speech *speech, const char *grammar_name)
70 {
71         return (speech->engine->deactivate ? speech->engine->deactivate(speech, grammar_name) : -1);
72 }
73
74 /*! \brief Load a local grammar on a speech structure */
75 int ast_speech_grammar_load(struct ast_speech *speech, const char *grammar_name, const char *grammar)
76 {
77         return (speech->engine->load ? speech->engine->load(speech, grammar_name, grammar) : -1);
78 }
79
80 /*! \brief Unload a local grammar from a speech structure */
81 int ast_speech_grammar_unload(struct ast_speech *speech, const char *grammar_name)
82 {
83         return (speech->engine->unload ? speech->engine->unload(speech, grammar_name) : -1);
84 }
85
86 /*! \brief Return the results of a recognition from the speech structure */
87 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech)
88 {
89         return (speech->engine->get ? speech->engine->get(speech) : NULL);
90 }
91
92 /*! \brief Free a list of results */
93 int ast_speech_results_free(struct ast_speech_result *result)
94 {
95         struct ast_speech_result *current_result = result, *prev_result = NULL;
96         int res = 0;
97
98         while (current_result != NULL) {
99                 prev_result = current_result;
100                 /* Deallocate what we can */
101                 if (current_result->text != NULL) {
102                         ast_free(current_result->text);
103                         current_result->text = NULL;
104                 }
105                 if (current_result->grammar != NULL) {
106                         ast_free(current_result->grammar);
107                         current_result->grammar = NULL;
108                 }
109                 /* Move on and then free ourselves */
110                 current_result = AST_LIST_NEXT(current_result, list);
111                 ast_free(prev_result);
112                 prev_result = NULL;
113         }
114
115         return res;
116 }
117
118 /*! \brief Start speech recognition on a speech structure */
119 void ast_speech_start(struct ast_speech *speech)
120 {
121
122         /* Clear any flags that may affect things */
123         ast_clear_flag(speech, AST_SPEECH_SPOKE);
124         ast_clear_flag(speech, AST_SPEECH_QUIET);
125         ast_clear_flag(speech, AST_SPEECH_HAVE_RESULTS);
126
127         /* If results are on the structure, free them since we are starting again */
128         if (speech->results) {
129                 ast_speech_results_free(speech->results);
130                 speech->results = NULL;
131         }
132
133         /* If the engine needs to start stuff up, do it */
134         if (speech->engine->start)
135                 speech->engine->start(speech);
136
137         return;
138 }
139
140 /*! \brief Write in signed linear audio to be recognized */
141 int ast_speech_write(struct ast_speech *speech, void *data, int len)
142 {
143         /* Make sure the speech engine is ready to accept audio */
144         if (speech->state != AST_SPEECH_STATE_READY)
145                 return -1;
146
147         return speech->engine->write(speech, data, len);
148 }
149
150 /*! \brief Signal to the engine that DTMF was received */
151 int ast_speech_dtmf(struct ast_speech *speech, const char *dtmf)
152 {
153         int res = 0;
154
155         if (speech->state != AST_SPEECH_STATE_READY)
156                 return -1;
157
158         if (speech->engine->dtmf != NULL) {
159                 res = speech->engine->dtmf(speech, dtmf);
160         }
161
162         return res;
163 }
164
165 /*! \brief Change an engine specific attribute */
166 int ast_speech_change(struct ast_speech *speech, const char *name, const char *value)
167 {
168         return (speech->engine->change ? speech->engine->change(speech, name, value) : -1);
169 }
170
171 /*! \brief Create a new speech structure using the engine specified */
172 struct ast_speech *ast_speech_new(const char *engine_name, int formats)
173 {
174         struct ast_speech_engine *engine = NULL;
175         struct ast_speech *new_speech = NULL;
176         int format = AST_FORMAT_SLINEAR;
177
178         /* Try to find the speech recognition engine that was requested */
179         if (!(engine = find_engine(engine_name)))
180                 return NULL;
181
182         /* Before even allocating the memory below do some codec negotiation, we choose the best codec possible and fall back to signed linear if possible */
183         if ((format = (engine->formats & formats)))
184                 format = ast_best_codec(format);
185         else if ((engine->formats & AST_FORMAT_SLINEAR))
186                 format = AST_FORMAT_SLINEAR;
187         else
188                 return NULL;
189
190         /* Allocate our own speech structure, and try to allocate a structure from the engine too */
191         if (!(new_speech = ast_calloc(1, sizeof(*new_speech))))
192                 return NULL;
193
194         /* Initialize the lock */
195         ast_mutex_init(&new_speech->lock);
196
197         /* Make sure no results are present */
198         new_speech->results = NULL;
199
200         /* Copy over our engine pointer */
201         new_speech->engine = engine;
202
203         /* Can't forget the format audio is going to be in */
204         new_speech->format = format;
205
206         /* We are not ready to accept audio yet */
207         ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
208
209         /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
210         if (engine->create(new_speech, format)) {
211                 ast_mutex_destroy(&new_speech->lock);
212                 ast_free(new_speech);
213                 new_speech = NULL;
214         }
215
216         return new_speech;
217 }
218
219 /*! \brief Destroy a speech structure */
220 int ast_speech_destroy(struct ast_speech *speech)
221 {
222         int res = 0;
223
224         /* Call our engine so we are destroyed properly */
225         speech->engine->destroy(speech);
226
227         /* Deinitialize the lock */
228         ast_mutex_destroy(&speech->lock);
229
230         /* If results exist on the speech structure, destroy them */
231         if (speech->results)
232                 ast_speech_results_free(speech->results);
233
234         /* If a processing sound is set - free the memory used by it */
235         if (speech->processing_sound)
236                 ast_free(speech->processing_sound);
237
238         /* Aloha we are done */
239         ast_free(speech);
240
241         return res;
242 }
243
244 /*! \brief Change state of a speech structure */
245 int ast_speech_change_state(struct ast_speech *speech, int state)
246 {
247         int res = 0;
248
249         switch (state) {
250         case AST_SPEECH_STATE_WAIT:
251                 /* The engine heard audio, so they spoke */
252                 ast_set_flag(speech, AST_SPEECH_SPOKE);
253         default:
254                 speech->state = state;
255                 break;
256         }
257
258         return res;
259 }
260
261 /*! \brief Change the type of results we want */
262 int ast_speech_change_results_type(struct ast_speech *speech, enum ast_speech_results_type results_type)
263 {
264         speech->results_type = results_type;
265
266         return (speech->engine->change_results_type ? speech->engine->change_results_type(speech, results_type) : 0);
267 }
268
269 /*! \brief Register a speech recognition engine */
270 int ast_speech_register(struct ast_speech_engine *engine)
271 {
272         struct ast_speech_engine *existing_engine = NULL;
273         int res = 0;
274
275         /* Confirm the engine meets the minimum API requirements */
276         if (!engine->create || !engine->write || !engine->destroy) {
277                 ast_log(LOG_WARNING, "Speech recognition engine '%s' did not meet minimum API requirements.\n", engine->name);
278                 return -1;
279         }
280
281         /* If an engine is already loaded with this name, error out */
282         if ((existing_engine = find_engine(engine->name))) {
283                 ast_log(LOG_WARNING, "Speech recognition engine '%s' already exists.\n", engine->name);
284                 return -1;
285         }
286
287         ast_verb(2, "Registered speech recognition engine '%s'\n", engine->name);
288
289         /* Add to the engine linked list and make default if needed */
290         AST_RWLIST_WRLOCK(&engines);
291         AST_RWLIST_INSERT_HEAD(&engines, engine, list);
292         if (!default_engine) {
293                 default_engine = engine;
294                 ast_verb(2, "Made '%s' the default speech recognition engine\n", engine->name);
295         }
296         AST_RWLIST_UNLOCK(&engines);
297
298         return res;
299 }
300
301 /*! \brief Unregister a speech recognition engine */
302 int ast_speech_unregister(const char *engine_name)
303 {
304         struct ast_speech_engine *engine = NULL;
305         int res = -1;
306
307         if (ast_strlen_zero(engine_name))
308                 return -1;
309
310         AST_RWLIST_WRLOCK(&engines);
311         AST_RWLIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
312                 if (!strcasecmp(engine->name, engine_name)) {
313                         /* We have our engine... removed it */
314                         AST_RWLIST_REMOVE_CURRENT(list);
315                         /* If this was the default engine, we need to pick a new one */
316                         if (engine == default_engine) {
317                                 default_engine = AST_RWLIST_FIRST(&engines);
318                         }
319                         ast_verb(2, "Unregistered speech recognition engine '%s'\n", engine_name);
320                         /* All went well */
321                         res = 0;
322                         break;
323                 }
324         }
325         AST_RWLIST_TRAVERSE_SAFE_END;
326         AST_RWLIST_UNLOCK(&engines);
327
328         return res;
329 }
330
331 static int unload_module(void)
332 {
333         /* We can not be unloaded */
334         return -1;
335 }
336
337 static int load_module(void)
338 {
339         return AST_MODULE_LOAD_SUCCESS;
340 }
341
342 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS, "Generic Speech Recognition API",
343                 .load = load_module,
344                 .unload = unload_module,
345                 );