Mon May 14 04:50:56 2007

Asterisk developer's documentation


res_speech.c File Reference

Generic Speech Recognition API. More...

#include "asterisk.h"
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <string.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/options.h"
#include "asterisk/speech.h"

Include dependency graph for res_speech.c:

Go to the source code of this file.

Functions

static AST_LIST_HEAD_STATIC (engines, ast_speech_engine)
 AST_MODULE_INFO (ASTERISK_GPL_KEY, AST_MODFLAG_GLOBAL_SYMBOLS,"Generic Speech Recognition API",.load=load_module,.unload=unload_module,)
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_grammar_activate (struct ast_speech *speech, char *grammar_name)
 Activate a grammar on a speech structure.
int ast_speech_grammar_deactivate (struct ast_speech *speech, char *grammar_name)
 Deactivate a grammar on a speech structure.
int ast_speech_grammar_load (struct ast_speech *speech, char *grammar_name, char *grammar)
 Load a grammar on a speech structure (not globally).
int ast_speech_grammar_unload (struct ast_speech *speech, char *grammar_name)
 Unload a grammar.
ast_speechast_speech_new (char *engine_name, int format)
 Create a new speech structure.
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 set of results.
ast_speech_resultast_speech_results_get (struct ast_speech *speech)
 Get speech recognition results.
void ast_speech_start (struct ast_speech *speech)
 Indicate to the speech engine that audio is now going to start being written.
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 audio to the speech engine.
 ASTERISK_FILE_VERSION (__FILE__,"$Revision$")
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_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 AST_LIST_HEAD_STATIC ( engines  ,
ast_speech_engine   
) [static]

AST_MODULE_INFO ( ASTERISK_GPL_KEY  ,
AST_MODFLAG_GLOBAL_SYMBOLS  ,
"Generic Speech Recognition API"  ,
load = load_module,
unload = unload_module 
)

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

Change an engine specific attribute.

Definition at line 196 of file res_speech.c.

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

Referenced by speech_engine_write().

00197 {
00198    int res = 0;
00199 
00200    if (speech->engine->change != NULL) {
00201       res = speech->engine->change(speech, name, value);
00202    }
00203 
00204    return res;
00205 }

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

00298 {
00299    int res = 0;
00300 
00301    speech->results_type = results_type;
00302 
00303    if (speech->engine->change_results_type)
00304       res = speech->engine->change_results_type(speech, results_type);
00305 
00306    return res;
00307 }

int ast_speech_change_state ( struct ast_speech speech,
int  state 
)

Change state of a speech structure.

Definition at line 280 of file res_speech.c.

References ast_set_flag, AST_SPEECH_SPOKE, and AST_SPEECH_STATE_WAIT.

Referenced by ast_speech_new(), and speech_background().

00281 {
00282    int res = 0;
00283 
00284    switch (state) {
00285    case AST_SPEECH_STATE_WAIT:
00286       /* The engine heard audio, so they spoke */
00287       ast_set_flag(speech, AST_SPEECH_SPOKE);
00288    default:
00289       speech->state = state;
00290       break;
00291    }
00292 
00293    return res;
00294 }

int ast_speech_destroy ( struct ast_speech speech  ) 

Destroy a speech structure.

Definition at line 250 of file res_speech.c.

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

Referenced by destroy_callback(), speech_background(), speech_create(), and speech_destroy().

00251 {
00252    int res = 0;
00253 
00254    /* Call our engine so we are destroyed properly */
00255    speech->engine->destroy(speech);
00256 
00257    /* Deinitialize the lock */
00258    ast_mutex_destroy(&speech->lock);
00259 
00260    /* If results exist on the speech structure, destroy them */
00261    if (speech->results != NULL) {
00262       ast_speech_results_free(speech->results);
00263       speech->results = NULL;
00264    }
00265 
00266    /* If a processing sound is set - free the memory used by it */
00267    if (speech->processing_sound != NULL) {
00268       free(speech->processing_sound);
00269       speech->processing_sound = NULL;
00270    }
00271 
00272    /* Aloha we are done */
00273    free(speech);
00274    speech = NULL;
00275 
00276    return res;
00277 }

int ast_speech_grammar_activate ( struct ast_speech speech,
char *  grammar_name 
)

Activate a grammar on a speech structure.

Definition at line 71 of file res_speech.c.

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

Referenced by speech_activate().

00072 {
00073    int res = 0;
00074 
00075    if (speech->engine->activate != NULL) {
00076       res = speech->engine->activate(speech, grammar_name);
00077    }
00078 
00079    return res;
00080 }

int ast_speech_grammar_deactivate ( struct ast_speech speech,
char *  grammar_name 
)

Deactivate a grammar on a speech structure.

Definition at line 83 of file res_speech.c.

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

Referenced by speech_deactivate().

00084 {
00085    int res = 0;
00086 
00087         if (speech->engine->deactivate != NULL) {
00088                 res = speech->engine->deactivate(speech, grammar_name);
00089         }
00090 
00091    return res;
00092 }

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

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

Definition at line 95 of file res_speech.c.

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

Referenced by speech_load().

00096 {
00097    int res = 0;
00098 
00099    if (speech->engine->load != NULL) {
00100       res = speech->engine->load(speech, grammar_name, grammar);
00101    }
00102 
00103    return res;
00104 }

int ast_speech_grammar_unload ( struct ast_speech speech,
char *  grammar_name 
)

Unload a grammar.

Definition at line 107 of file res_speech.c.

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

Referenced by speech_unload().

00108 {
00109         int res = 0;
00110 
00111         if (speech->engine->unload != NULL) {
00112                 res = speech->engine->unload(speech, grammar_name);
00113         }
00114 
00115         return res;
00116 }

struct ast_speech* ast_speech_new ( char *  engine_name,
int  format 
)

Create a new speech structure.

Definition at line 208 of file res_speech.c.

References ast_calloc, ast_mutex_destroy(), ast_mutex_init(), ast_speech_change_state(), AST_SPEECH_STATE_NOT_READY, ast_speech::engine, find_engine(), free, and ast_speech_engine::new.

Referenced by speech_create().

00209 {
00210    struct ast_speech_engine *engine = NULL;
00211    struct ast_speech *new_speech = NULL;
00212 
00213    /* Try to find the speech recognition engine that was requested */
00214    engine = find_engine(engine_name);
00215    if (engine == NULL) {
00216       /* Invalid engine or no engine available */
00217       return NULL;
00218    }
00219 
00220    /* Allocate our own speech structure, and try to allocate a structure from the engine too */
00221    new_speech = ast_calloc(1, sizeof(*new_speech));
00222    if (new_speech == NULL) {
00223       /* Ran out of memory while trying to allocate some for a speech structure */
00224       return NULL;
00225    }
00226 
00227    /* Initialize the lock */
00228    ast_mutex_init(&new_speech->lock);
00229 
00230    /* Make sure no results are present */
00231    new_speech->results = NULL;
00232 
00233    /* Copy over our engine pointer */
00234    new_speech->engine = engine;
00235 
00236    /* We are not ready to accept audio yet */
00237    ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
00238 
00239    /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
00240    if (engine->new(new_speech)) {
00241       ast_mutex_destroy(&new_speech->lock);
00242       free(new_speech);
00243       new_speech = NULL;
00244    }
00245 
00246    return new_speech;
00247 }

int ast_speech_register ( struct ast_speech_engine engine  ) 

Register a speech recognition engine.

Definition at line 310 of file res_speech.c.

References AST_LIST_INSERT_HEAD, AST_LIST_LOCK, AST_LIST_UNLOCK, ast_verbose(), default_engine, find_engine(), ast_speech_engine::name, option_verbose, and VERBOSE_PREFIX_2.

00311 {
00312    struct ast_speech_engine *existing_engine = NULL;
00313    int res = 0;
00314 
00315    existing_engine = find_engine(engine->name);
00316    if (existing_engine != NULL) {
00317       /* Engine already loaded */
00318       return -1;
00319    }
00320 
00321    if (option_verbose > 1)
00322       ast_verbose(VERBOSE_PREFIX_2 "Registered speech recognition engine '%s'\n", engine->name);
00323 
00324    /* Add to the engine linked list and make default if needed */
00325    AST_LIST_LOCK(&engines);
00326    AST_LIST_INSERT_HEAD(&engines, engine, list);
00327    if (default_engine == NULL) {
00328       default_engine = engine;
00329       if (option_verbose > 1)
00330          ast_verbose(VERBOSE_PREFIX_2 "Made '%s' the default speech recognition engine\n", engine->name);
00331    }
00332    AST_LIST_UNLOCK(&engines);
00333 
00334    return res;
00335 }

int ast_speech_results_free ( struct ast_speech_result result  ) 

Free a set of results.

Definition at line 131 of file res_speech.c.

References free, ast_speech_result::grammar, ast_speech_result::next, result, and ast_speech_result::text.

Referenced by ast_speech_destroy(), and ast_speech_start().

00132 {
00133    struct ast_speech_result *current_result = result, *prev_result = NULL;
00134    int res = 0;
00135 
00136    while (current_result != NULL) {
00137       prev_result = current_result;
00138       /* Deallocate what we can */
00139       if (current_result->text != NULL) {
00140          free(current_result->text);
00141          current_result->text = NULL;
00142       }
00143       if (current_result->grammar != NULL) {
00144          free(current_result->grammar);
00145          current_result->grammar = NULL;
00146       }
00147       /* Move on and then free ourselves */
00148       current_result = current_result->next;
00149       free(prev_result);
00150       prev_result = NULL;
00151    }
00152 
00153    return res;
00154 }

struct ast_speech_result* ast_speech_results_get ( struct ast_speech speech  ) 

Get speech recognition results.

Definition at line 119 of file res_speech.c.

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

Referenced by speech_background().

00120 {
00121    struct ast_speech_result *result = NULL;
00122 
00123    if (speech->engine->get != NULL) {
00124       result = speech->engine->get(speech);
00125    }
00126 
00127    return result;
00128 }

void ast_speech_start ( struct ast_speech speech  ) 

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

Definition at line 157 of file res_speech.c.

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

Referenced by speech_background(), and speech_start().

00158 {
00159 
00160    /* Clear any flags that may affect things */
00161    ast_clear_flag(speech, AST_SPEECH_SPOKE);
00162    ast_clear_flag(speech, AST_SPEECH_QUIET);
00163 
00164    /* If results are on the structure, free them since we are starting again */
00165    if (speech->results != NULL) {
00166       ast_speech_results_free(speech->results);
00167       speech->results = NULL;
00168    }
00169 
00170    /* If the engine needs to start stuff up, do it */
00171    if (speech->engine->start != NULL) {
00172       speech->engine->start(speech);
00173    }
00174 
00175    return;
00176 }

int ast_speech_unregister ( char *  engine_name  ) 

Unregister a speech recognition engine.

Definition at line 338 of file res_speech.c.

References AST_LIST_FIRST, AST_LIST_LOCK, AST_LIST_REMOVE_CURRENT, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, AST_LIST_UNLOCK, ast_verbose(), default_engine, ast_speech_engine::name, option_verbose, and VERBOSE_PREFIX_2.

00339 {
00340    struct ast_speech_engine *engine = NULL;
00341    int res = -1;
00342 
00343    if (engine_name == NULL) {
00344       return res;
00345    }
00346 
00347    AST_LIST_LOCK(&engines);
00348    AST_LIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
00349       if (!strcasecmp(engine->name, engine_name)) {
00350          /* We have our engine... removed it */
00351          AST_LIST_REMOVE_CURRENT(&engines, list);
00352          /* If this was the default engine, we need to pick a new one */
00353          if (default_engine == engine) {
00354             default_engine = AST_LIST_FIRST(&engines);
00355          }
00356          if (option_verbose > 1)
00357             ast_verbose(VERBOSE_PREFIX_2 "Unregistered speech recognition engine '%s'\n", engine_name);
00358          /* All went well */
00359          res = 0;
00360          break;
00361       }
00362    }
00363    AST_LIST_TRAVERSE_SAFE_END
00364    AST_LIST_UNLOCK(&engines);
00365 
00366    return res;
00367 }

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

Write audio to the speech engine.

Definition at line 179 of file res_speech.c.

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

Referenced by speech_background().

00180 {
00181    int res = 0;
00182 
00183    /* Make sure the speech engine is ready to accept audio */
00184    if (speech->state != AST_SPEECH_STATE_READY) {
00185       return -1;
00186    }
00187 
00188    if (speech->engine->write != NULL) {
00189       speech->engine->write(speech, data, len);
00190    }
00191 
00192    return res;
00193 }

ASTERISK_FILE_VERSION ( __FILE__  ,
"$Revision$"   
)

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

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

Definition at line 49 of file res_speech.c.

References AST_LIST_LOCK, AST_LIST_TRAVERSE_SAFE_BEGIN, AST_LIST_TRAVERSE_SAFE_END, AST_LIST_UNLOCK, default_engine, and ast_speech_engine::name.

00050 {
00051    struct ast_speech_engine *engine = NULL;
00052 
00053    /* If no name is specified -- use the default engine */
00054    if (engine_name == NULL || strlen(engine_name) == 0) {
00055       return default_engine;
00056    }
00057 
00058    AST_LIST_LOCK(&engines);
00059    AST_LIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
00060       if (!strcasecmp(engine->name, engine_name)) {
00061          break;
00062       }
00063    }
00064    AST_LIST_TRAVERSE_SAFE_END
00065    AST_LIST_UNLOCK(&engines);
00066 
00067    return engine;
00068 }

static int load_module ( void   )  [static]

Definition at line 375 of file res_speech.c.

References AST_LIST_HEAD_INIT_NOLOCK.

00376 {
00377    int res = 0;
00378 
00379    /* Initialize our list of engines */
00380    AST_LIST_HEAD_INIT_NOLOCK(&engines);
00381 
00382    return res;
00383 }

static int unload_module ( void   )  [static]

Definition at line 369 of file res_speech.c.

00370 {
00371    /* We can not be unloaded */
00372    return -1;
00373 }


Variable Documentation

struct ast_speech_engine* default_engine = NULL [static]

Definition at line 46 of file res_speech.c.

Referenced by ast_speech_register(), ast_speech_unregister(), and find_engine().


Generated on Mon May 14 04:50:57 2007 for Asterisk - the Open Source PBX by  doxygen 1.5.1