Wed Oct 28 11:46:19 2009

Asterisk developer's documentation


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 dependency graph for res_speech.c:

Go to the source code of this file.

Data Structures

struct  engines

Functions

static void __fini_engines (void)
static void __init_engines (void)
static void __reg_module (void)
static void __unreg_module (void)
int ast_speech_change (struct ast_speech *speech, char *name, const char *value)
 Change an engine specific attribute.
int ast_speech_change_results_type (struct ast_speech *speech, enum ast_speech_results_type results_type)
 Change the type of results we want.
int ast_speech_change_state (struct ast_speech *speech, int state)
 Change state of a speech structure.
int ast_speech_destroy (struct ast_speech *speech)
 Destroy a speech structure.
int ast_speech_dtmf (struct ast_speech *speech, const char *dtmf)
 Signal to the engine that DTMF was received.
int ast_speech_grammar_activate (struct ast_speech *speech, char *grammar_name)
 Activate a loaded (either local or global) grammar.
int ast_speech_grammar_deactivate (struct ast_speech *speech, char *grammar_name)
 Deactivate a loaded grammar on a speech structure.
int ast_speech_grammar_load (struct ast_speech *speech, char *grammar_name, char *grammar)
 Load a local grammar on a speech structure.
int ast_speech_grammar_unload (struct ast_speech *speech, char *grammar_name)
 Unload a local grammar from a speech structure.
struct ast_speechast_speech_new (char *engine_name, int formats)
 Create a new speech structure using the engine specified.
int ast_speech_register (struct ast_speech_engine *engine)
 Register a speech recognition engine.
int ast_speech_results_free (struct ast_speech_result *result)
 Free a list of results.
struct ast_speech_resultast_speech_results_get (struct ast_speech *speech)
 Return the results of a recognition from the speech structure.
void ast_speech_start (struct ast_speech *speech)
 Start speech recognition on a speech structure.
int ast_speech_unregister (char *engine_name)
 Unregister a speech recognition engine.
int ast_speech_write (struct ast_speech *speech, void *data, int len)
 Write in signed linear audio to be recognized.
 ASTERISK_FILE_VERSION (__FILE__,"$Revision: 89511 $")
static struct ast_speech_enginefind_engine (char *engine_name)
 Find a speech recognition engine of specified name, if NULL then use the default one.
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 , .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, .load = load_module, .unload = unload_module, }
static const struct
ast_module_info
ast_module_info = &__mod_info
static struct ast_speech_enginedefault_engine = NULL


Detailed Description

Generic Speech Recognition API.

Author:
Joshua Colp <jcolp@digium.com>

Definition in file res_speech.c.


Function Documentation

static void __fini_engines ( void   )  [static]

Definition at line 39 of file res_speech.c.

00044 {

static void __init_engines ( void   )  [static]

Definition at line 39 of file res_speech.c.

00044 {

static void __reg_module ( void   )  [static]

Definition at line 344 of file res_speech.c.

static void __unreg_module ( void   )  [static]

Definition at line 344 of file res_speech.c.

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

Change an engine specific attribute.

Definition at line 166 of file res_speech.c.

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

Referenced by handle_speechset(), and speech_engine_write().

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

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 262 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().

00263 {
00264    speech->results_type = results_type;
00265 
00266    return (speech->engine->change_results_type ? speech->engine->change_results_type(speech, results_type) : 0);
00267 }

int ast_speech_change_state ( struct ast_speech speech,
int  state 
)

Change state of a speech structure.

Definition at line 245 of file res_speech.c.

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

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

00246 {
00247    int res = 0;
00248 
00249    switch (state) {
00250    case AST_SPEECH_STATE_WAIT:
00251       /* The engine heard audio, so they spoke */
00252       ast_set_flag(speech, AST_SPEECH_SPOKE);
00253    default:
00254       speech->state = state;
00255       break;
00256    }
00257 
00258    return res;
00259 }

int ast_speech_destroy ( struct ast_speech speech  ) 

Destroy a speech structure.

Definition at line 220 of file res_speech.c.

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

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

00221 {
00222    int res = 0;
00223 
00224    /* Call our engine so we are destroyed properly */
00225    speech->engine->destroy(speech);
00226 
00227    /* Deinitialize the lock */
00228    ast_mutex_destroy(&speech->lock);
00229 
00230    /* If results exist on the speech structure, destroy them */
00231    if (speech->results)
00232       ast_speech_results_free(speech->results);
00233 
00234    /* If a processing sound is set - free the memory used by it */
00235    if (speech->processing_sound)
00236       ast_free(speech->processing_sound);
00237 
00238    /* Aloha we are done */
00239    ast_free(speech);
00240 
00241    return res;
00242 }

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

Signal to the engine that DTMF was received.

Definition at line 151 of file res_speech.c.

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

Referenced by speech_background().

00152 {
00153    int res = 0;
00154 
00155    if (speech->state != AST_SPEECH_STATE_READY)
00156       return -1;
00157 
00158    if (speech->engine->dtmf != NULL) {
00159       res = speech->engine->dtmf(speech, dtmf);
00160    }
00161 
00162    return res;
00163 }

int ast_speech_grammar_activate ( struct ast_speech speech,
char *  grammar_name 
)

Activate a loaded (either local or global) grammar.

Activate a grammar on a speech structure.

Definition at line 63 of file res_speech.c.

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

Referenced by handle_speechactivategrammar(), and speech_activate().

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

int ast_speech_grammar_deactivate ( struct ast_speech speech,
char *  grammar_name 
)

Deactivate a loaded grammar on a speech structure.

Deactivate a grammar on a speech structure.

Definition at line 69 of file res_speech.c.

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

Referenced by handle_speechdeactivategrammar(), and speech_deactivate().

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

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

Load a local grammar on a speech structure.

Load a grammar on a speech structure (not globally).

Definition at line 75 of file res_speech.c.

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

Referenced by handle_speechloadgrammar(), and speech_load().

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

int ast_speech_grammar_unload ( struct ast_speech speech,
char *  grammar_name 
)

Unload a local grammar from a speech structure.

Unload a grammar.

Definition at line 81 of file res_speech.c.

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

Referenced by handle_speechunloadgrammar(), and speech_unload().

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

struct ast_speech* ast_speech_new ( char *  engine_name,
int  formats 
) [read]

Create a new speech structure using the engine specified.

Create a new speech structure.

Definition at line 172 of file res_speech.c.

References ast_best_codec(), ast_calloc, AST_FORMAT_SLINEAR, 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, format, ast_speech_engine::formats, ast_speech::lock, and ast_speech::results.

Referenced by handle_speechcreate(), and speech_create().

00173 {
00174    struct ast_speech_engine *engine = NULL;
00175    struct ast_speech *new_speech = NULL;
00176    int format = AST_FORMAT_SLINEAR;
00177 
00178    /* Try to find the speech recognition engine that was requested */
00179    if (!(engine = find_engine(engine_name)))
00180       return NULL;
00181 
00182    /* Before even allocating the memory below do some codec negotiation, we choose the best codec possible and fall back to signed linear if possible */
00183    if ((format = (engine->formats & formats)))
00184       format = ast_best_codec(format);
00185    else if ((engine->formats & AST_FORMAT_SLINEAR))
00186       format = AST_FORMAT_SLINEAR;
00187    else
00188       return NULL;
00189 
00190    /* Allocate our own speech structure, and try to allocate a structure from the engine too */
00191    if (!(new_speech = ast_calloc(1, sizeof(*new_speech))))
00192       return NULL;
00193 
00194    /* Initialize the lock */
00195    ast_mutex_init(&new_speech->lock);
00196 
00197    /* Make sure no results are present */
00198    new_speech->results = NULL;
00199 
00200    /* Copy over our engine pointer */
00201    new_speech->engine = engine;
00202 
00203    /* Can't forget the format audio is going to be in */
00204    new_speech->format = format;
00205 
00206    /* We are not ready to accept audio yet */
00207    ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
00208 
00209    /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
00210    if (engine->create(new_speech, format)) {
00211       ast_mutex_destroy(&new_speech->lock);
00212       ast_free(new_speech);
00213       new_speech = NULL;
00214    }
00215 
00216    return new_speech;
00217 }

int ast_speech_register ( struct ast_speech_engine engine  ) 

Register a speech recognition engine.

Definition at line 270 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.

00271 {
00272    struct ast_speech_engine *existing_engine = NULL;
00273    int res = 0;
00274 
00275    /* Confirm the engine meets the minimum API requirements */
00276    if (!engine->create || !engine->write || !engine->destroy) {
00277       ast_log(LOG_WARNING, "Speech recognition engine '%s' did not meet minimum API requirements.\n", engine->name);
00278       return -1;
00279    }
00280 
00281    /* If an engine is already loaded with this name, error out */
00282    if ((existing_engine = find_engine(engine->name))) {
00283       ast_log(LOG_WARNING, "Speech recognition engine '%s' already exists.\n", engine->name);
00284       return -1;
00285    }
00286 
00287    ast_verb(2, "Registered speech recognition engine '%s'\n", engine->name);
00288 
00289    /* Add to the engine linked list and make default if needed */
00290    AST_RWLIST_WRLOCK(&engines);
00291    AST_RWLIST_INSERT_HEAD(&engines, engine, list);
00292    if (!default_engine) {
00293       default_engine = engine;
00294       ast_verb(2, "Made '%s' the default speech recognition engine\n", engine->name);
00295    }
00296    AST_RWLIST_UNLOCK(&engines);
00297 
00298    return res;
00299 }

int ast_speech_results_free ( struct ast_speech_result result  ) 

Free a list of results.

Free a set of results.

Definition at line 93 of file res_speech.c.

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

Referenced by ast_speech_destroy(), and ast_speech_start().

00094 {
00095    struct ast_speech_result *current_result = result, *prev_result = NULL;
00096    int res = 0;
00097 
00098    while (current_result != NULL) {
00099       prev_result = current_result;
00100       /* Deallocate what we can */
00101       if (current_result->text != NULL) {
00102          ast_free(current_result->text);
00103          current_result->text = NULL;
00104       }
00105       if (current_result->grammar != NULL) {
00106          ast_free(current_result->grammar);
00107          current_result->grammar = NULL;
00108       }
00109       /* Move on and then free ourselves */
00110       current_result = AST_LIST_NEXT(current_result, list);
00111       ast_free(prev_result);
00112       prev_result = NULL;
00113    }
00114 
00115    return res;
00116 }

struct ast_speech_result* ast_speech_results_get ( struct ast_speech speech  )  [read]

Return the results of a recognition from the speech structure.

Get speech recognition results.

Definition at line 87 of file res_speech.c.

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

Referenced by handle_speechrecognize(), and speech_background().

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

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 119 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, ast_speech::results, and ast_speech_engine::start.

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

00120 {
00121 
00122    /* Clear any flags that may affect things */
00123    ast_clear_flag(speech, AST_SPEECH_SPOKE);
00124    ast_clear_flag(speech, AST_SPEECH_QUIET);
00125    ast_clear_flag(speech, AST_SPEECH_HAVE_RESULTS);
00126 
00127    /* If results are on the structure, free them since we are starting again */
00128    if (speech->results) {
00129       ast_speech_results_free(speech->results);
00130       speech->results = NULL;
00131    }
00132 
00133    /* If the engine needs to start stuff up, do it */
00134    if (speech->engine->start)
00135       speech->engine->start(speech);
00136 
00137    return;
00138 }

int ast_speech_unregister ( char *  engine_name  ) 

Unregister a speech recognition engine.

Definition at line 302 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, and ast_speech_engine::name.

00303 {
00304    struct ast_speech_engine *engine = NULL;
00305    int res = -1;
00306 
00307    if (ast_strlen_zero(engine_name))
00308       return -1;
00309 
00310    AST_RWLIST_WRLOCK(&engines);
00311    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
00312       if (!strcasecmp(engine->name, engine_name)) {
00313          /* We have our engine... removed it */
00314          AST_RWLIST_REMOVE_CURRENT(list);
00315          /* If this was the default engine, we need to pick a new one */
00316          if (!default_engine)
00317             default_engine = AST_RWLIST_FIRST(&engines);
00318          ast_verb(2, "Unregistered speech recognition engine '%s'\n", engine_name);
00319          /* All went well */
00320          res = 0;
00321          break;
00322       }
00323    }
00324    AST_RWLIST_TRAVERSE_SAFE_END;
00325    AST_RWLIST_UNLOCK(&engines);
00326 
00327    return res;
00328 }

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 141 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().

00142 {
00143    /* Make sure the speech engine is ready to accept audio */
00144    if (speech->state != AST_SPEECH_STATE_READY)
00145       return -1;
00146 
00147    return speech->engine->write(speech, data, len);
00148 }

ASTERISK_FILE_VERSION ( __FILE__  ,
"$Revision: 89511 $"   
)

static struct ast_speech_engine* find_engine ( char *  engine_name  )  [static, read]

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

Definition at line 43 of file res_speech.c.

References AST_RWLIST_RDLOCK, AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, ast_strlen_zero(), and ast_speech_engine::name.

00044 {
00045    struct ast_speech_engine *engine = NULL;
00046 
00047    /* If no name is specified -- use the default engine */
00048    if (ast_strlen_zero(engine_name))
00049       return default_engine;
00050 
00051    AST_RWLIST_RDLOCK(&engines);
00052    AST_RWLIST_TRAVERSE(&engines, engine, list) {
00053       if (!strcasecmp(engine->name, engine_name)) {
00054          break;
00055       }
00056    }
00057    AST_RWLIST_UNLOCK(&engines);
00058 
00059    return engine;
00060 }

static int load_module ( void   )  [static]

Definition at line 336 of file res_speech.c.

References AST_MODULE_LOAD_SUCCESS.

00337 {
00338    return AST_MODULE_LOAD_SUCCESS;
00339 }

static int unload_module ( void   )  [static]

Definition at line 330 of file res_speech.c.

00331 {
00332    /* We can not be unloaded */
00333    return -1;
00334 }


Variable Documentation

struct ast_module_info __mod_info = { .name = AST_MODULE, .flags = AST_MODFLAG_GLOBAL_SYMBOLS , .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, .load = load_module, .unload = unload_module, } [static]

Definition at line 344 of file res_speech.c.

const struct ast_module_info* ast_module_info = &__mod_info [static]

Definition at line 344 of file res_speech.c.

struct ast_speech_engine* default_engine = NULL [static]

Definition at line 40 of file res_speech.c.


Generated on Wed Oct 28 11:46:19 2009 for Asterisk - the Open Source PBX by  doxygen 1.5.6