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