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