res_speech.c File Reference

Generic Speech Recognition API. More...

#include "asterisk.h"
#include "asterisk/channel.h"
#include "asterisk/module.h"
#include "asterisk/lock.h"
#include "asterisk/linkedlists.h"
#include "asterisk/cli.h"
#include "asterisk/term.h"
#include "asterisk/speech.h"
#include "asterisk/format_cache.h"

Include dependency graph for res_speech.c:

Go to the source code of this file.

Data Structures
struct	engines

Functions
static void	__reg_module (void)
static void	__unreg_module (void)
struct ast_module *	AST_MODULE_SELF_SYM (void)
int	ast_speech_change (struct ast_speech *speech, const char *name, const char *value)
	Change an engine specific attribute. More...
int	ast_speech_change_results_type (struct ast_speech *speech, enum ast_speech_results_type results_type)
	Change the type of results we want. More...
int	ast_speech_change_state (struct ast_speech *speech, int state)
	Change state of a speech structure. More...
int	ast_speech_destroy (struct ast_speech *speech)
	Destroy a speech structure. More...
int	ast_speech_dtmf (struct ast_speech *speech, const char *dtmf)
	Signal to the engine that DTMF was received. More...
int	ast_speech_get_setting (struct ast_speech *speech, const char *name, char *buf, size_t len)
	Get an engine specific attribute. More...
int	ast_speech_grammar_activate (struct ast_speech *speech, const char *grammar_name)
	Activate a loaded (either local or global) grammar. More...
int	ast_speech_grammar_deactivate (struct ast_speech *speech, const char *grammar_name)
	Deactivate a loaded grammar on a speech structure. More...
int	ast_speech_grammar_load (struct ast_speech *speech, const char *grammar_name, const char *grammar)
	Load a local grammar on a speech structure. More...
int	ast_speech_grammar_unload (struct ast_speech *speech, const char *grammar_name)
	Unload a local grammar from a speech structure. More...
struct ast_speech *	ast_speech_new (const char *engine_name, const struct ast_format_cap *cap)
	Create a new speech structure using the engine specified. More...
int	ast_speech_register (struct ast_speech_engine *engine)
	Register a speech recognition engine. More...
int	ast_speech_results_free (struct ast_speech_result *result)
	Free a list of results. More...
struct ast_speech_result *	ast_speech_results_get (struct ast_speech *speech)
	Return the results of a recognition from the speech structure. More...
void	ast_speech_start (struct ast_speech *speech)
	Start speech recognition on a speech structure. More...
int	ast_speech_unregister (const char *engine_name)
	Unregister a speech recognition engine. More...
int	ast_speech_write (struct ast_speech *speech, void *data, int len)
	Write in signed linear audio to be recognized. More...
static struct ast_speech_engine *	find_engine (const char *engine_name)
	Find a speech recognition engine of specified name, if NULL then use the default one. More...
static int	load_module (void)
static int	unload_module (void)

Variables
static struct ast_module_info	__mod_info = { .name = AST_MODULE, .flags = AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER , .description = "Generic Speech Recognition API" , .key = "This paragraph is copyright (c) 2006 by Digium, Inc. \In order for your module to load, it must return this \key via a function called \"key\". Any code which \includes this paragraph must be licensed under the GNU \General Public License version 2 or later (at your \option). In addition to Digium's general reservations \of rights, Digium expressly reserves the right to \allow other parties to license this paragraph under \different terms. Any use of Digium, Inc. trademarks or \logos (including \"Asterisk\" or \"Digium\") without \express written permission of Digium, Inc. is prohibited.\n" , .buildopt_sum = AST_BUILDOPT_SUM, .support_level = AST_MODULE_SUPPORT_CORE, .load = load_module, .unload = unload_module, .load_pri = AST_MODPRI_APP_DEPEND - 1, }
static const struct ast_module_info *	ast_module_info = &__mod_info
static struct ast_speech_engine *	default_engine = NULL
static struct engines	engines = { .first = NULL, .last = NULL, .lock = { PTHREAD_RWLOCK_INITIALIZER , NULL, {1, 0} } , }

Detailed Description

Generic Speech Recognition API.

Author

Joshua Colp jcolp.nosp@m.@dig.nosp@m.ium.c.nosp@m.om

Definition in file res_speech.c.

Function Documentation

__reg_module()

static void __reg_module ( void  )

static

Definition at line 368 of file res_speech.c.

__unreg_module()

static void __unreg_module ( void  )

static

Definition at line 368 of file res_speech.c.

AST_MODULE_SELF_SYM()

struct ast_module* AST_MODULE_SELF_SYM

(

void

)

Definition at line 368 of file res_speech.c.

ast_speech_change()

int ast_speech_change	(	struct ast_speech *	speech,
		const char *	name,
		const char *	value
	)

Change an engine specific attribute.

Definition at line 168 of file res_speech.c.

References ast_speech_engine::change, and ast_speech::engine.

Referenced by handle_speechset(), and speech_engine_write().

{
   return (speech->engine->change ? speech->engine->change(speech, name, value) : -1);
}

ast_speech_change_results_type()

int ast_speech_change_results_type	(	struct ast_speech *	speech,
		enum ast_speech_results_type	results_type
	)

Change the type of results we want.

Definition at line 284 of file res_speech.c.

References ast_speech_engine::change_results_type, ast_speech::engine, and ast_speech::results_type.

Referenced by speech_results_type_write().

{
   speech->results_type = results_type;

   return (speech->engine->change_results_type ? speech->engine->change_results_type(speech, results_type) : 0);
}

ast_speech_change_state()

int ast_speech_change_state	(	struct ast_speech *	speech,
		int	state
	)

Change state of a speech structure.

Definition at line 267 of file res_speech.c.

References ast_set_flag, AST_SPEECH_SPOKE, AST_SPEECH_STATE_WAIT, ast_speech::state, and state.

Referenced by ast_speech_new(), handle_speechrecognize(), and speech_background().

{
   int res = 0;

   switch (state) {
   case AST_SPEECH_STATE_WAIT:
      /* The engine heard audio, so they spoke */
      ast_set_flag(speech, AST_SPEECH_SPOKE);
   default:
      speech->state = state;
      break;
   }

   return res;
}

ast_speech_destroy()

int ast_speech_destroy

(

struct ast_speech *

speech

)

Destroy a speech structure.

Definition at line 240 of file res_speech.c.

References ao2_ref, ast_free, ast_mutex_destroy, ast_speech_results_free(), ast_speech_engine::destroy, ast_speech::engine, ast_speech::format, ast_speech::lock, ast_speech::processing_sound, and ast_speech::results.

Referenced by destroy_callback(), handle_speechdestroy(), launch_asyncagi(), run_agi(), and speech_create().

{
   int res = 0;

   /* Call our engine so we are destroyed properly */
   speech->engine->destroy(speech);

   /* Deinitialize the lock */
   ast_mutex_destroy(&speech->lock);

   /* If results exist on the speech structure, destroy them */
   if (speech->results)
      ast_speech_results_free(speech->results);

   /* If a processing sound is set - free the memory used by it */
   if (speech->processing_sound)
      ast_free(speech->processing_sound);

   ao2_ref(speech->format, -1);

   /* Aloha we are done */
   ast_free(speech);

   return res;
}

ast_speech_dtmf()

int ast_speech_dtmf	(	struct ast_speech *	speech,
		const char *	dtmf
	)

Signal to the engine that DTMF was received.

Definition at line 153 of file res_speech.c.

References AST_SPEECH_STATE_READY, ast_speech_engine::dtmf, ast_speech::engine, NULL, and ast_speech::state.

Referenced by speech_background().

{
   int res = 0;

   if (speech->state != AST_SPEECH_STATE_READY)
      return -1;

   if (speech->engine->dtmf != NULL) {
      res = speech->engine->dtmf(speech, dtmf);
   }

   return res;
}

ast_speech_get_setting()

int ast_speech_get_setting	(	struct ast_speech *	speech,
		const char *	name,
		char *	buf,
		size_t	len
	)

Get an engine specific attribute.

Definition at line 174 of file res_speech.c.

References ast_speech::engine, and ast_speech_engine::get_setting.

Referenced by speech_engine_read().

{
   return (speech->engine->get_setting ? speech->engine->get_setting(speech, name, buf, len) : -1);
}

ast_speech_grammar_activate()

int ast_speech_grammar_activate	(	struct ast_speech *	speech,
		const char *	grammar_name
	)

Activate a loaded (either local or global) grammar.

Activate a grammar on a speech structure.

Definition at line 65 of file res_speech.c.

References ast_speech_engine::activate, and ast_speech::engine.

Referenced by handle_speechactivategrammar(), and speech_activate().

{
   return (speech->engine->activate ? speech->engine->activate(speech, grammar_name) : -1);
}

ast_speech_grammar_deactivate()

int ast_speech_grammar_deactivate	(	struct ast_speech *	speech,
		const char *	grammar_name
	)

Deactivate a loaded grammar on a speech structure.

Deactivate a grammar on a speech structure.

Definition at line 71 of file res_speech.c.

References ast_speech_engine::deactivate, and ast_speech::engine.

Referenced by handle_speechdeactivategrammar(), and speech_deactivate().

{
   return (speech->engine->deactivate ? speech->engine->deactivate(speech, grammar_name) : -1);
}

ast_speech_grammar_load()

int ast_speech_grammar_load	(	struct ast_speech *	speech,
		const char *	grammar_name,
		const char *	grammar
	)

Load a local grammar on a speech structure.

Load a grammar on a speech structure (not globally)

Definition at line 77 of file res_speech.c.

References ast_speech::engine, and ast_speech_engine::load.

Referenced by handle_speechloadgrammar(), and speech_load().

{
   return (speech->engine->load ? speech->engine->load(speech, grammar_name, grammar) : -1);
}

ast_speech_grammar_unload()

int ast_speech_grammar_unload	(	struct ast_speech *	speech,
		const char *	grammar_name
	)

Unload a local grammar from a speech structure.

Unload a grammar.

Definition at line 83 of file res_speech.c.

References ast_speech::engine, and ast_speech_engine::unload.

Referenced by handle_speechunloadgrammar(), and speech_unload().

{
   return (speech->engine->unload ? speech->engine->unload(speech, grammar_name) : -1);
}

ast_speech_new()

struct ast_speech* ast_speech_new	(	const char *	engine_name,
		const struct ast_format_cap *	cap
	)

Create a new speech structure using the engine specified.

Create a new speech structure.

Definition at line 180 of file res_speech.c.

References ao2_bump, ao2_cleanup, ao2_ref, ast_calloc, ast_format_cap_alloc, AST_FORMAT_CAP_FLAG_DEFAULT, ast_format_cap_get_compatible(), ast_format_cap_get_format(), ast_format_cap_iscompatible_format(), AST_FORMAT_CMP_NOT_EQUAL, ast_format_slin, ast_free, ast_mutex_destroy, ast_mutex_init, ast_speech_change_state(), AST_SPEECH_STATE_NOT_READY, ast_speech_engine::create, ast_speech::engine, find_engine(), ast_speech::format, ast_speech_engine::formats, ast_speech::lock, NULL, RAII_VAR, and ast_speech::results.

Referenced by handle_speechcreate(), and speech_create().

{
   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 */
   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 */
   if (!(new_speech = ast_calloc(1, sizeof(*new_speech)))) {
      return NULL;
   }

   /* Initialize the lock */
   ast_mutex_init(&new_speech->lock);

   /* Make sure no results are present */
   new_speech->results = NULL;

   /* Copy over our engine pointer */
   new_speech->engine = engine;

   /* Can't forget the format audio is going to be in */
   new_speech->format = ao2_bump(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->create(new_speech, new_speech->format)) {
      ast_mutex_destroy(&new_speech->lock);
      ao2_ref(new_speech->format, -1);
      ast_free(new_speech);
      return NULL;
   }

   return new_speech;
}

ast_speech_register()

int ast_speech_register

(

struct ast_speech_engine *

engine

)

Register a speech recognition engine.

Definition at line 292 of file res_speech.c.

References ast_log, AST_RWLIST_INSERT_HEAD, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_verb, ast_speech_engine::create, ast_speech_engine::destroy, find_engine(), LOG_WARNING, ast_speech_engine::name, and ast_speech_engine::write.

{
   int res = 0;

   /* 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 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_RWLIST_WRLOCK(&engines);
   AST_RWLIST_INSERT_HEAD(&engines, engine, list);
   if (!default_engine) {
      default_engine = engine;
      ast_verb(2, "Made '%s' the default speech recognition engine\n", engine->name);
   }
   AST_RWLIST_UNLOCK(&engines);

   return res;
}

ast_speech_results_free()

int ast_speech_results_free

(

struct ast_speech_result *

result

)

Free a list of results.

Free a set of results.

Definition at line 95 of file res_speech.c.

References ast_free, AST_LIST_NEXT, ast_speech_result::grammar, NULL, result, and ast_speech_result::text.

Referenced by ast_speech_destroy(), and ast_speech_start().

{
   struct ast_speech_result *current_result = result, *prev_result = NULL;
   int res = 0;

   while (current_result != NULL) {
      prev_result = current_result;
      /* Deallocate what we can */
      if (current_result->text != NULL) {
         ast_free(current_result->text);
         current_result->text = NULL;
      }
      if (current_result->grammar != NULL) {
         ast_free(current_result->grammar);
         current_result->grammar = NULL;
      }
      /* Move on and then free ourselves */
      current_result = AST_LIST_NEXT(current_result, list);
      ast_free(prev_result);
      prev_result = NULL;
   }

   return res;
}

ast_speech_results_get()

struct ast_speech_result* ast_speech_results_get

(

struct ast_speech *

speech

)

Return the results of a recognition from the speech structure.

Get speech recognition results.

Definition at line 89 of file res_speech.c.

References ast_speech::engine, ast_speech_engine::get, and NULL.

Referenced by handle_speechrecognize(), and speech_background().

{
   return (speech->engine->get ? speech->engine->get(speech) : NULL);
}

ast_speech_start()

void ast_speech_start

(

struct ast_speech *

speech

)

Start speech recognition on a speech structure.

Indicate to the speech engine that audio is now going to start being written.

Definition at line 121 of file res_speech.c.

References ast_clear_flag, AST_SPEECH_HAVE_RESULTS, AST_SPEECH_QUIET, ast_speech_results_free(), AST_SPEECH_SPOKE, ast_speech::engine, NULL, ast_speech::results, and ast_speech_engine::start.

Referenced by handle_speechrecognize(), speech_background(), and speech_start().

{

   /* 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) {
      ast_speech_results_free(speech->results);
      speech->results = NULL;
   }

   /* If the engine needs to start stuff up, do it */
   if (speech->engine->start)
      speech->engine->start(speech);

   return;
}

ast_speech_unregister()

int ast_speech_unregister

(

const char *

engine_name

)

Unregister a speech recognition engine.

Definition at line 323 of file res_speech.c.

References AST_RWLIST_FIRST, AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_strlen_zero, ast_verb, ast_speech_engine::name, and NULL.

{
   struct ast_speech_engine *engine = NULL;
   int res = -1;

   if (ast_strlen_zero(engine_name))
      return -1;

   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_RWLIST_REMOVE_CURRENT(list);
         /* If this was the default engine, we need to pick a new one */
         if (engine == default_engine) {
            default_engine = AST_RWLIST_FIRST(&engines);
         }
         ast_verb(2, "Unregistered speech recognition engine '%s'\n", engine_name);
         /* All went well */
         res = 0;
         break;
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END;
   AST_RWLIST_UNLOCK(&engines);

   return res;
}

ast_speech_write()

int ast_speech_write	(	struct ast_speech *	speech,
		void *	data,
		int	len
	)

Write in signed linear audio to be recognized.

Write audio to the speech engine.

Definition at line 143 of file res_speech.c.

References AST_SPEECH_STATE_READY, ast_speech::engine, ast_speech::state, and ast_speech_engine::write.

Referenced by handle_speechrecognize(), and speech_background().

{
   /* 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);
}

find_engine()

static struct ast_speech_engine* find_engine ( const char *  engine_name )

static

Find a speech recognition engine of specified name, if NULL then use the default one.

Definition at line 45 of file res_speech.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, ast_strlen_zero, default_engine, ast_speech_engine::name, and NULL.

Referenced by ast_speech_new(), and ast_speech_register().

{
   struct ast_speech_engine *engine = NULL;

   /* If no name is specified -- use the default engine */
   if (ast_strlen_zero(engine_name))
      return default_engine;

   AST_RWLIST_RDLOCK(&engines);
   AST_RWLIST_TRAVERSE(&engines, engine, list) {
      if (!strcasecmp(engine->name, engine_name)) {
         break;
      }
   }
   AST_RWLIST_UNLOCK(&engines);

   return engine;
}

load_module()

static int load_module ( void  )

static

Definition at line 358 of file res_speech.c.

References AST_MODFLAG_GLOBAL_SYMBOLS, AST_MODFLAG_LOAD_ORDER, AST_MODPRI_APP_DEPEND, AST_MODULE_INFO(), AST_MODULE_LOAD_SUCCESS, AST_MODULE_SUPPORT_CORE, ASTERISK_GPL_KEY, ast_speech_engine::load, ast_speech_engine::unload, and unload_module().

{
   return AST_MODULE_LOAD_SUCCESS;
}

unload_module()

static int unload_module ( void  )

static

Definition at line 352 of file res_speech.c.

Referenced by load_module().

{
   /* We can not be unloaded */
   return -1;
}

Variable Documentation

__mod_info

struct ast_module_info __mod_info = { .name = AST_MODULE, .flags = AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER , .description = "Generic Speech Recognition API" , .key = "This paragraph is copyright (c) 2006 by Digium, Inc. \In order for your module to load, it must return this \key via a function called \"key\". Any code which \includes this paragraph must be licensed under the GNU \General Public License version 2 or later (at your \option). In addition to Digium's general reservations \of rights, Digium expressly reserves the right to \allow other parties to license this paragraph under \different terms. Any use of Digium, Inc. trademarks or \logos (including \"Asterisk\" or \"Digium\") without \express written permission of Digium, Inc. is prohibited.\n" , .buildopt_sum = AST_BUILDOPT_SUM, .support_level = AST_MODULE_SUPPORT_CORE, .load = load_module, .unload = unload_module, .load_pri = AST_MODPRI_APP_DEPEND - 1, }

static

Definition at line 368 of file res_speech.c.

ast_module_info

const struct ast_module_info* ast_module_info = &__mod_info

static

Definition at line 368 of file res_speech.c.

default_engine

struct ast_speech_engine* default_engine = NULL

static

Definition at line 42 of file res_speech.c.

Referenced by find_engine().

engines

struct engines engines = { .first = NULL, .last = NULL, .lock = { PTHREAD_RWLOCK_INITIALIZER , NULL, {1, 0} } , }

static