Mon Aug 31 12:30:12 2015

Asterisk developer's documentation


res_speech.c

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2006, Digium, Inc.
00005  *
00006  * Joshua Colp <jcolp@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  *
00021  * \brief Generic Speech Recognition API
00022  *
00023  * \author Joshua Colp <jcolp@digium.com>
00024  */
00025 
00026 /*** MODULEINFO
00027    <support_level>core</support_level>
00028  ***/
00029 
00030 #include "asterisk.h"
00031 
00032 ASTERISK_FILE_VERSION(__FILE__, "$Revision: 368738 $");
00033 
00034 #include "asterisk/channel.h"
00035 #include "asterisk/module.h"
00036 #include "asterisk/lock.h"
00037 #include "asterisk/linkedlists.h"
00038 #include "asterisk/cli.h"
00039 #include "asterisk/term.h"
00040 #include "asterisk/speech.h"
00041 
00042 
00043 static AST_RWLIST_HEAD_STATIC(engines, ast_speech_engine);
00044 static struct ast_speech_engine *default_engine = NULL;
00045 
00046 /*! \brief Find a speech recognition engine of specified name, if NULL then use the default one */
00047 static struct ast_speech_engine *find_engine(const char *engine_name)
00048 {
00049    struct ast_speech_engine *engine = NULL;
00050 
00051    /* If no name is specified -- use the default engine */
00052    if (ast_strlen_zero(engine_name))
00053       return default_engine;
00054 
00055    AST_RWLIST_RDLOCK(&engines);
00056    AST_RWLIST_TRAVERSE(&engines, engine, list) {
00057       if (!strcasecmp(engine->name, engine_name)) {
00058          break;
00059       }
00060    }
00061    AST_RWLIST_UNLOCK(&engines);
00062 
00063    return engine;
00064 }
00065 
00066 /*! \brief Activate a loaded (either local or global) grammar */
00067 int ast_speech_grammar_activate(struct ast_speech *speech, const char *grammar_name)
00068 {
00069    return (speech->engine->activate ? speech->engine->activate(speech, grammar_name) : -1);
00070 }
00071 
00072 /*! \brief Deactivate a loaded grammar on a speech structure */
00073 int ast_speech_grammar_deactivate(struct ast_speech *speech, const char *grammar_name)
00074 {
00075    return (speech->engine->deactivate ? speech->engine->deactivate(speech, grammar_name) : -1);
00076 }
00077 
00078 /*! \brief Load a local grammar on a speech structure */
00079 int ast_speech_grammar_load(struct ast_speech *speech, const char *grammar_name, const char *grammar)
00080 {
00081    return (speech->engine->load ? speech->engine->load(speech, grammar_name, grammar) : -1);
00082 }
00083 
00084 /*! \brief Unload a local grammar from a speech structure */
00085 int ast_speech_grammar_unload(struct ast_speech *speech, const char *grammar_name)
00086 {
00087    return (speech->engine->unload ? speech->engine->unload(speech, grammar_name) : -1);
00088 }
00089 
00090 /*! \brief Return the results of a recognition from the speech structure */
00091 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech)
00092 {
00093    return (speech->engine->get ? speech->engine->get(speech) : NULL);
00094 }
00095 
00096 /*! \brief Free a list of results */
00097 int ast_speech_results_free(struct ast_speech_result *result)
00098 {
00099    struct ast_speech_result *current_result = result, *prev_result = NULL;
00100    int res = 0;
00101 
00102    while (current_result != NULL) {
00103       prev_result = current_result;
00104       /* Deallocate what we can */
00105       if (current_result->text != NULL) {
00106          ast_free(current_result->text);
00107          current_result->text = NULL;
00108       }
00109       if (current_result->grammar != NULL) {
00110          ast_free(current_result->grammar);
00111          current_result->grammar = NULL;
00112       }
00113       /* Move on and then free ourselves */
00114       current_result = AST_LIST_NEXT(current_result, list);
00115       ast_free(prev_result);
00116       prev_result = NULL;
00117    }
00118 
00119    return res;
00120 }
00121 
00122 /*! \brief Start speech recognition on a speech structure */
00123 void ast_speech_start(struct ast_speech *speech)
00124 {
00125 
00126    /* Clear any flags that may affect things */
00127    ast_clear_flag(speech, AST_SPEECH_SPOKE);
00128    ast_clear_flag(speech, AST_SPEECH_QUIET);
00129    ast_clear_flag(speech, AST_SPEECH_HAVE_RESULTS);
00130 
00131    /* If results are on the structure, free them since we are starting again */
00132    if (speech->results) {
00133       ast_speech_results_free(speech->results);
00134       speech->results = NULL;
00135    }
00136 
00137    /* If the engine needs to start stuff up, do it */
00138    if (speech->engine->start)
00139       speech->engine->start(speech);
00140 
00141    return;
00142 }
00143 
00144 /*! \brief Write in signed linear audio to be recognized */
00145 int ast_speech_write(struct ast_speech *speech, void *data, int len)
00146 {
00147    /* Make sure the speech engine is ready to accept audio */
00148    if (speech->state != AST_SPEECH_STATE_READY)
00149       return -1;
00150 
00151    return speech->engine->write(speech, data, len);
00152 }
00153 
00154 /*! \brief Signal to the engine that DTMF was received */
00155 int ast_speech_dtmf(struct ast_speech *speech, const char *dtmf)
00156 {
00157    int res = 0;
00158 
00159    if (speech->state != AST_SPEECH_STATE_READY)
00160       return -1;
00161 
00162    if (speech->engine->dtmf != NULL) {
00163       res = speech->engine->dtmf(speech, dtmf);
00164    }
00165 
00166    return res;
00167 }
00168 
00169 /*! \brief Change an engine specific attribute */
00170 int ast_speech_change(struct ast_speech *speech, const char *name, const char *value)
00171 {
00172    return (speech->engine->change ? speech->engine->change(speech, name, value) : -1);
00173 }
00174 
00175 /*! \brief Create a new speech structure using the engine specified */
00176 struct ast_speech *ast_speech_new(const char *engine_name, int formats)
00177 {
00178    struct ast_speech_engine *engine = NULL;
00179    struct ast_speech *new_speech = NULL;
00180    int format = AST_FORMAT_SLINEAR;
00181 
00182    /* Try to find the speech recognition engine that was requested */
00183    if (!(engine = find_engine(engine_name)))
00184       return NULL;
00185 
00186    /* Before even allocating the memory below do some codec negotiation, we choose the best codec possible and fall back to signed linear if possible */
00187    if ((format = (engine->formats & formats)))
00188       format = ast_best_codec(format);
00189    else if ((engine->formats & AST_FORMAT_SLINEAR))
00190       format = AST_FORMAT_SLINEAR;
00191    else
00192       return NULL;
00193 
00194    /* Allocate our own speech structure, and try to allocate a structure from the engine too */
00195    if (!(new_speech = ast_calloc(1, sizeof(*new_speech))))
00196       return NULL;
00197 
00198    /* Initialize the lock */
00199    ast_mutex_init(&new_speech->lock);
00200 
00201    /* Make sure no results are present */
00202    new_speech->results = NULL;
00203 
00204    /* Copy over our engine pointer */
00205    new_speech->engine = engine;
00206 
00207    /* Can't forget the format audio is going to be in */
00208    new_speech->format = format;
00209 
00210    /* We are not ready to accept audio yet */
00211    ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
00212 
00213    /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
00214    if (engine->create(new_speech, format)) {
00215       ast_mutex_destroy(&new_speech->lock);
00216       ast_free(new_speech);
00217       new_speech = NULL;
00218    }
00219 
00220    return new_speech;
00221 }
00222 
00223 /*! \brief Destroy a speech structure */
00224 int ast_speech_destroy(struct ast_speech *speech)
00225 {
00226    int res = 0;
00227 
00228    /* Call our engine so we are destroyed properly */
00229    speech->engine->destroy(speech);
00230 
00231    /* Deinitialize the lock */
00232    ast_mutex_destroy(&speech->lock);
00233 
00234    /* If results exist on the speech structure, destroy them */
00235    if (speech->results)
00236       ast_speech_results_free(speech->results);
00237 
00238    /* If a processing sound is set - free the memory used by it */
00239    if (speech->processing_sound)
00240       ast_free(speech->processing_sound);
00241 
00242    /* Aloha we are done */
00243    ast_free(speech);
00244 
00245    return res;
00246 }
00247 
00248 /*! \brief Change state of a speech structure */
00249 int ast_speech_change_state(struct ast_speech *speech, int state)
00250 {
00251    int res = 0;
00252 
00253    if (state == AST_SPEECH_STATE_WAIT) {
00254       /* The engine heard audio, so they spoke */
00255       ast_set_flag(speech, AST_SPEECH_SPOKE);
00256    }
00257 
00258    speech->state = state;
00259 
00260    return res;
00261 }
00262 
00263 /*! \brief Change the type of results we want */
00264 int ast_speech_change_results_type(struct ast_speech *speech, enum ast_speech_results_type results_type)
00265 {
00266    speech->results_type = results_type;
00267 
00268    return (speech->engine->change_results_type ? speech->engine->change_results_type(speech, results_type) : 0);
00269 }
00270 
00271 /*! \brief Register a speech recognition engine */
00272 int ast_speech_register(struct ast_speech_engine *engine)
00273 {
00274    int res = 0;
00275 
00276    /* Confirm the engine meets the minimum API requirements */
00277    if (!engine->create || !engine->write || !engine->destroy) {
00278       ast_log(LOG_WARNING, "Speech recognition engine '%s' did not meet minimum API requirements.\n", engine->name);
00279       return -1;
00280    }
00281 
00282    /* If an engine is already loaded with this name, error out */
00283    if (find_engine(engine->name)) {
00284       ast_log(LOG_WARNING, "Speech recognition engine '%s' already exists.\n", engine->name);
00285       return -1;
00286    }
00287 
00288    ast_verb(2, "Registered speech recognition engine '%s'\n", engine->name);
00289 
00290    /* Add to the engine linked list and make default if needed */
00291    AST_RWLIST_WRLOCK(&engines);
00292    AST_RWLIST_INSERT_HEAD(&engines, engine, list);
00293    if (!default_engine) {
00294       default_engine = engine;
00295       ast_verb(2, "Made '%s' the default speech recognition engine\n", engine->name);
00296    }
00297    AST_RWLIST_UNLOCK(&engines);
00298 
00299    return res;
00300 }
00301 
00302 /*! \brief Unregister a speech recognition engine */
00303 int ast_speech_unregister(const char *engine_name)
00304 {
00305    struct ast_speech_engine *engine = NULL;
00306    int res = -1;
00307 
00308    if (ast_strlen_zero(engine_name))
00309       return -1;
00310 
00311    AST_RWLIST_WRLOCK(&engines);
00312    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
00313       if (!strcasecmp(engine->name, engine_name)) {
00314          /* We have our engine... removed it */
00315          AST_RWLIST_REMOVE_CURRENT(list);
00316          /* If this was the default engine, we need to pick a new one */
00317          if (engine == default_engine) {
00318             default_engine = AST_RWLIST_FIRST(&engines);
00319          }
00320          ast_verb(2, "Unregistered speech recognition engine '%s'\n", engine_name);
00321          /* All went well */
00322          res = 0;
00323          break;
00324       }
00325    }
00326    AST_RWLIST_TRAVERSE_SAFE_END;
00327    AST_RWLIST_UNLOCK(&engines);
00328 
00329    return res;
00330 }
00331 
00332 static int unload_module(void)
00333 {
00334    /* We can not be unloaded */
00335    return -1;
00336 }
00337 
00338 static int load_module(void)
00339 {
00340    return AST_MODULE_LOAD_SUCCESS;
00341 }
00342 
00343 AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER, "Generic Speech Recognition API",
00344       .load = load_module,
00345       .unload = unload_module,
00346       .load_pri = AST_MODPRI_APP_DEPEND,
00347       );

Generated on 31 Aug 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1