Merge "Fix ast_(v)asprintf() malloc failure usage conditions."
[asterisk/asterisk.git] / res / res_speech.c
index f06638a..d6c5329 100644 (file)
  * \author Joshua Colp <jcolp@digium.com>
  */
 
-#include "asterisk.h"
-
-ASTERISK_FILE_VERSION(__FILE__, "$Revision$");
+/*** MODULEINFO
+       <support_level>core</support_level>
+ ***/
 
-#include <stdio.h>
-#include <stdlib.h>
-#include <unistd.h>
-#include <string.h>
+#include "asterisk.h"
 
 #include "asterisk/channel.h"
 #include "asterisk/module.h"
@@ -38,93 +35,60 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$");
 #include "asterisk/linkedlists.h"
 #include "asterisk/cli.h"
 #include "asterisk/term.h"
-#include "asterisk/options.h"
 #include "asterisk/speech.h"
+#include "asterisk/format_cache.h"
 
-
-static AST_LIST_HEAD_STATIC(engines, ast_speech_engine);
+static AST_RWLIST_HEAD_STATIC(engines, ast_speech_engine);
 static struct ast_speech_engine *default_engine = NULL;
 
 /*! \brief Find a speech recognition engine of specified name, if NULL then use the default one */
-static struct ast_speech_engine *find_engine(char *engine_name)
+static struct ast_speech_engine *find_engine(const char *engine_name)
 {
        struct ast_speech_engine *engine = NULL;
 
        /* If no name is specified -- use the default engine */
-       if (engine_name == NULL || strlen(engine_name) == 0) {
+       if (ast_strlen_zero(engine_name))
                return default_engine;
-       }
 
-       AST_LIST_LOCK(&engines);
-       AST_LIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
+       AST_RWLIST_RDLOCK(&engines);
+       AST_RWLIST_TRAVERSE(&engines, engine, list) {
                if (!strcasecmp(engine->name, engine_name)) {
                        break;
                }
        }
-       AST_LIST_TRAVERSE_SAFE_END
-       AST_LIST_UNLOCK(&engines);
+       AST_RWLIST_UNLOCK(&engines);
 
        return engine;
 }
 
 /*! \brief Activate a loaded (either local or global) grammar */
-int ast_speech_grammar_activate(struct ast_speech *speech, char *grammar_name)
+int ast_speech_grammar_activate(struct ast_speech *speech, const char *grammar_name)
 {
-       int res = 0;
-
-       if (speech->engine->activate != NULL) {
-               res = speech->engine->activate(speech, grammar_name);
-       }
-
-       return res;
+       return (speech->engine->activate ? speech->engine->activate(speech, grammar_name) : -1);
 }
 
 /*! \brief Deactivate a loaded grammar on a speech structure */
-int ast_speech_grammar_deactivate(struct ast_speech *speech, char *grammar_name)
+int ast_speech_grammar_deactivate(struct ast_speech *speech, const char *grammar_name)
 {
-       int res = 0;
-
-        if (speech->engine->deactivate != NULL) {
-                res = speech->engine->deactivate(speech, grammar_name);
-        }
-
-       return res;
+       return (speech->engine->deactivate ? speech->engine->deactivate(speech, grammar_name) : -1);
 }
 
 /*! \brief Load a local grammar on a speech structure */
-int ast_speech_grammar_load(struct ast_speech *speech, char *grammar_name, char *grammar)
+int ast_speech_grammar_load(struct ast_speech *speech, const char *grammar_name, const char *grammar)
 {
-       int res = 0;
-
-       if (speech->engine->load != NULL) {
-               res = speech->engine->load(speech, grammar_name, grammar);
-       }
-
-       return res;
+       return (speech->engine->load ? speech->engine->load(speech, grammar_name, grammar) : -1);
 }
 
 /*! \brief Unload a local grammar from a speech structure */
-int ast_speech_grammar_unload(struct ast_speech *speech, char *grammar_name)
+int ast_speech_grammar_unload(struct ast_speech *speech, const char *grammar_name)
 {
-        int res = 0;
-
-        if (speech->engine->unload != NULL) {
-                res = speech->engine->unload(speech, grammar_name);
-        }
-
-        return res;
+       return (speech->engine->unload ? speech->engine->unload(speech, grammar_name) : -1);
 }
 
 /*! \brief Return the results of a recognition from the speech structure */
 struct ast_speech_result *ast_speech_results_get(struct ast_speech *speech)
 {
-       struct ast_speech_result *result = NULL;
-
-       if (speech->engine->get != NULL) {
-               result = speech->engine->get(speech);
-       }
-
-       return result;
+       return (speech->engine->get ? speech->engine->get(speech) : NULL);
 }
 
 /*! \brief Free a list of results */
@@ -137,16 +101,16 @@ int ast_speech_results_free(struct ast_speech_result *result)
                prev_result = current_result;
                /* Deallocate what we can */
                if (current_result->text != NULL) {
-                       free(current_result->text);
+                       ast_free(current_result->text);
                        current_result->text = NULL;
                }
                if (current_result->grammar != NULL) {
-                       free(current_result->grammar);
+                       ast_free(current_result->grammar);
                        current_result->grammar = NULL;
                }
                /* Move on and then free ourselves */
-               current_result = current_result->next;
-               free(prev_result);
+               current_result = AST_LIST_NEXT(current_result, list);
+               ast_free(prev_result);
                prev_result = NULL;
        }
 
@@ -160,17 +124,17 @@ void ast_speech_start(struct ast_speech *speech)
        /* Clear any flags that may affect things */
        ast_clear_flag(speech, AST_SPEECH_SPOKE);
        ast_clear_flag(speech, AST_SPEECH_QUIET);
+       ast_clear_flag(speech, AST_SPEECH_HAVE_RESULTS);
 
        /* If results are on the structure, free them since we are starting again */
-       if (speech->results != NULL) {
+       if (speech->results) {
                ast_speech_results_free(speech->results);
                speech->results = NULL;
        }
 
        /* If the engine needs to start stuff up, do it */
-       if (speech->engine->start != NULL) {
+       if (speech->engine->start)
                speech->engine->start(speech);
-       }
 
        return;
 }
@@ -178,49 +142,71 @@ void ast_speech_start(struct ast_speech *speech)
 /*! \brief Write in signed linear audio to be recognized */
 int ast_speech_write(struct ast_speech *speech, void *data, int len)
 {
+       /* Make sure the speech engine is ready to accept audio */
+       if (speech->state != AST_SPEECH_STATE_READY)
+               return -1;
+
+       return speech->engine->write(speech, data, len);
+}
+
+/*! \brief Signal to the engine that DTMF was received */
+int ast_speech_dtmf(struct ast_speech *speech, const char *dtmf)
+{
        int res = 0;
 
-       /* Make sure the speech engine is ready to accept audio */
-       if (speech->state != AST_SPEECH_STATE_READY) {
+       if (speech->state != AST_SPEECH_STATE_READY)
                return -1;
-       }
 
-       if (speech->engine->write != NULL) {
-               speech->engine->write(speech, data, len);
+       if (speech->engine->dtmf != NULL) {
+               res = speech->engine->dtmf(speech, dtmf);
        }
 
        return res;
 }
 
 /*! \brief Change an engine specific attribute */
-int ast_speech_change(struct ast_speech *speech, char *name, const char *value)
+int ast_speech_change(struct ast_speech *speech, const char *name, const char *value)
 {
-       int res = 0;
-
-       if (speech->engine->change != NULL) {
-               res = speech->engine->change(speech, name, value);
-       }
+       return (speech->engine->change ? speech->engine->change(speech, name, value) : -1);
+}
 
-       return res;
+/*! \brief Get an engine specific attribute */
+int ast_speech_get_setting(struct ast_speech *speech, const char *name, char *buf, size_t len)
+{
+       return (speech->engine->get_setting ? speech->engine->get_setting(speech, name, buf, len) : -1);
 }
 
 /*! \brief Create a new speech structure using the engine specified */
-struct ast_speech *ast_speech_new(char *engine_name, int format)
+struct ast_speech *ast_speech_new(const char *engine_name, const struct ast_format_cap *cap)
 {
        struct ast_speech_engine *engine = NULL;
        struct ast_speech *new_speech = NULL;
+       struct ast_format_cap *joint;
+       RAII_VAR(struct ast_format *, best, NULL, ao2_cleanup);
 
        /* Try to find the speech recognition engine that was requested */
-       engine = find_engine(engine_name);
-       if (engine == NULL) {
-               /* Invalid engine or no engine available */
+       if (!(engine = find_engine(engine_name)))
+               return NULL;
+
+       joint = ast_format_cap_alloc(AST_FORMAT_CAP_FLAG_DEFAULT);
+       if (!joint) {
                return NULL;
        }
 
+       ast_format_cap_get_compatible(engine->formats, cap, joint);
+       best = ast_format_cap_get_format(joint, 0);
+       ao2_ref(joint, -1);
+
+       if (!best) {
+               if (ast_format_cap_iscompatible_format(engine->formats, ast_format_slin) != AST_FORMAT_CMP_NOT_EQUAL) {
+                       best = ao2_bump(ast_format_slin);
+               } else {
+                       return NULL;
+               }
+       }
+
        /* Allocate our own speech structure, and try to allocate a structure from the engine too */
-       new_speech = ast_calloc(1, sizeof(*new_speech));
-       if (new_speech == NULL) {
-               /* Ran out of memory while trying to allocate some for a speech structure */
+       if (!(new_speech = ast_calloc(1, sizeof(*new_speech)))) {
                return NULL;
        }
 
@@ -233,13 +219,16 @@ struct ast_speech *ast_speech_new(char *engine_name, int format)
        /* Copy over our engine pointer */
        new_speech->engine = engine;
 
+       /* Can't forget the format audio is going to be in */
+       new_speech->format = best;
+
        /* We are not ready to accept audio yet */
        ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
 
        /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
-       if (engine->new(new_speech)) {
+       if (engine->create(new_speech, best)) {
                ast_mutex_destroy(&new_speech->lock);
-               free(new_speech);
+               ast_free(new_speech);
                new_speech = NULL;
        }
 
@@ -258,20 +247,17 @@ int ast_speech_destroy(struct ast_speech *speech)
        ast_mutex_destroy(&speech->lock);
 
        /* If results exist on the speech structure, destroy them */
-       if (speech->results != NULL) {
+       if (speech->results)
                ast_speech_results_free(speech->results);
-               speech->results = NULL;
-       }
 
        /* If a processing sound is set - free the memory used by it */
-       if (speech->processing_sound != NULL) {
-               free(speech->processing_sound);
-               speech->processing_sound = NULL;
-       }
+       if (speech->processing_sound)
+               ast_free(speech->processing_sound);
+
+       ao2_ref(speech->format, -1);
 
        /* Aloha we are done */
-       free(speech);
-       speech = NULL;
+       ast_free(speech);
 
        return res;
 }
@@ -293,62 +279,71 @@ int ast_speech_change_state(struct ast_speech *speech, int state)
        return res;
 }
 
+/*! \brief Change the type of results we want */
+int ast_speech_change_results_type(struct ast_speech *speech, enum ast_speech_results_type results_type)
+{
+       speech->results_type = results_type;
+
+       return (speech->engine->change_results_type ? speech->engine->change_results_type(speech, results_type) : 0);
+}
+
 /*! \brief Register a speech recognition engine */
 int ast_speech_register(struct ast_speech_engine *engine)
 {
-       struct ast_speech_engine *existing_engine = NULL;
        int res = 0;
 
-       existing_engine = find_engine(engine->name);
-       if (existing_engine != NULL) {
-               /* Engine already loaded */
+       /* Confirm the engine meets the minimum API requirements */
+       if (!engine->create || !engine->write || !engine->destroy) {
+               ast_log(LOG_WARNING, "Speech recognition engine '%s' did not meet minimum API requirements.\n", engine->name);
                return -1;
        }
 
-       if (option_verbose > 1)
-               ast_verbose(VERBOSE_PREFIX_2 "Registered speech recognition engine '%s'\n", engine->name);
+       /* If an engine is already loaded with this name, error out */
+       if (find_engine(engine->name)) {
+               ast_log(LOG_WARNING, "Speech recognition engine '%s' already exists.\n", engine->name);
+               return -1;
+       }
+
+       ast_verb(2, "Registered speech recognition engine '%s'\n", engine->name);
 
        /* Add to the engine linked list and make default if needed */
-       AST_LIST_LOCK(&engines);
-       AST_LIST_INSERT_HEAD(&engines, engine, list);
-       if (default_engine == NULL) {
+       AST_RWLIST_WRLOCK(&engines);
+       AST_RWLIST_INSERT_HEAD(&engines, engine, list);
+       if (!default_engine) {
                default_engine = engine;
-               if (option_verbose > 1)
-                       ast_verbose(VERBOSE_PREFIX_2 "Made '%s' the default speech recognition engine\n", engine->name);
+               ast_verb(2, "Made '%s' the default speech recognition engine\n", engine->name);
        }
-       AST_LIST_UNLOCK(&engines);
+       AST_RWLIST_UNLOCK(&engines);
 
        return res;
 }
 
 /*! \brief Unregister a speech recognition engine */
-int ast_speech_unregister(char *engine_name)
+int ast_speech_unregister(const char *engine_name)
 {
        struct ast_speech_engine *engine = NULL;
        int res = -1;
 
-       if (engine_name == NULL) {
-               return res;
-       }
+       if (ast_strlen_zero(engine_name))
+               return -1;
 
-       AST_LIST_LOCK(&engines);
-       AST_LIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
+       AST_RWLIST_WRLOCK(&engines);
+       AST_RWLIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
                if (!strcasecmp(engine->name, engine_name)) {
                        /* We have our engine... removed it */
-                       AST_LIST_REMOVE_CURRENT(&engines, list);
+                       AST_RWLIST_REMOVE_CURRENT(list);
                        /* If this was the default engine, we need to pick a new one */
-                       if (default_engine == engine) {
-                               default_engine = AST_LIST_FIRST(&engines);
+                       if (engine == default_engine) {
+                               default_engine = AST_RWLIST_FIRST(&engines);
                        }
-                       if (option_verbose > 1)
-                               ast_verbose(VERBOSE_PREFIX_2 "Unregistered speech recognition engine '%s'\n", engine_name);
+                       ast_verb(2, "Unregistered speech recognition engine '%s'\n", engine_name);
                        /* All went well */
                        res = 0;
                        break;
                }
        }
-       AST_LIST_TRAVERSE_SAFE_END
-       AST_LIST_UNLOCK(&engines);
+       AST_RWLIST_TRAVERSE_SAFE_END;
+       AST_RWLIST_UNLOCK(&engines);
 
        return res;
 }
@@ -361,15 +356,12 @@ static int unload_module(void)
 
 static int load_module(void)
 {
-       int res = 0;
-
-       /* Initialize our list of engines */
-       AST_LIST_HEAD_INIT_NOLOCK(&engines);
-
-       return res;
+       return AST_MODULE_LOAD_SUCCESS;
 }
 
-AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS, "Generic Speech Recognition API",
-               .load = load_module,
-               .unload = unload_module,
-               );
+AST_MODULE_INFO(ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER, "Generic Speech Recognition API",
+       .support_level = AST_MODULE_SUPPORT_CORE,
+       .load = load_module,
+       .unload = unload_module,
+       .load_pri = AST_MODPRI_APP_DEPEND,
+);