Sat Aug 6 00:40:04 2011

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"

Go to the source code of this file.

Data Structures

struct  engines

Functions

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 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: 81406 $")
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 | AST_MODFLAG_BUILDSUM, .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 = "361d7bb937402d51e4658efb5b4d76e4" , .load = load_module, .unload = unload_module, }
static const struct ast_module_infoast_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 __reg_module ( void   )  [static]

Definition at line 404 of file res_speech.c.

static void __unreg_module ( void   )  [static]

Definition at line 404 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 212 of file res_speech.c.

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

Referenced by speech_engine_write().

00213 {
00214    int res = 0;
00215 
00216    if (speech->engine->change != NULL) {
00217       res = speech->engine->change(speech, name, value);
00218    }
00219 
00220    return res;
00221 }

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

00314 {
00315    int res = 0;
00316 
00317    speech->results_type = results_type;
00318 
00319    if (speech->engine->change_results_type)
00320       res = speech->engine->change_results_type(speech, results_type);
00321 
00322    return res;
00323 }

int ast_speech_change_state ( struct ast_speech speech,
int  state 
)

Change state of a speech structure.

Definition at line 296 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().

00297 {
00298    int res = 0;
00299 
00300    switch (state) {
00301    case AST_SPEECH_STATE_WAIT:
00302       /* The engine heard audio, so they spoke */
00303       ast_set_flag(speech, AST_SPEECH_SPOKE);
00304    default:
00305       speech->state = state;
00306       break;
00307    }
00308 
00309    return res;
00310 }

int ast_speech_destroy ( struct ast_speech speech  ) 

Destroy a speech structure.

Definition at line 266 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().

00267 {
00268    int res = 0;
00269 
00270    /* Call our engine so we are destroyed properly */
00271    speech->engine->destroy(speech);
00272 
00273    /* Deinitialize the lock */
00274    ast_mutex_destroy(&speech->lock);
00275 
00276    /* If results exist on the speech structure, destroy them */
00277    if (speech->results != NULL) {
00278       ast_speech_results_free(speech->results);
00279       speech->results = NULL;
00280    }
00281 
00282    /* If a processing sound is set - free the memory used by it */
00283    if (speech->processing_sound != NULL) {
00284       free(speech->processing_sound);
00285       speech->processing_sound = NULL;
00286    }
00287 
00288    /* Aloha we are done */
00289    free(speech);
00290    speech = NULL;
00291 
00292    return res;
00293 }

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

Signal to the engine that DTMF was received.

Definition at line 197 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().

00198 {
00199    int res = 0;
00200 
00201    if (speech->state != AST_SPEECH_STATE_READY)
00202       return -1;
00203 
00204    if (speech->engine->dtmf != NULL) {
00205       res = speech->engine->dtmf(speech, dtmf);
00206    }
00207 
00208    return res;
00209 }

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 224 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::create, ast_speech::engine, find_engine(), and free.

Referenced by speech_create().

00225 {
00226    struct ast_speech_engine *engine = NULL;
00227    struct ast_speech *new_speech = NULL;
00228 
00229    /* Try to find the speech recognition engine that was requested */
00230    engine = find_engine(engine_name);
00231    if (engine == NULL) {
00232       /* Invalid engine or no engine available */
00233       return NULL;
00234    }
00235 
00236    /* Allocate our own speech structure, and try to allocate a structure from the engine too */
00237    new_speech = ast_calloc(1, sizeof(*new_speech));
00238    if (new_speech == NULL) {
00239       /* Ran out of memory while trying to allocate some for a speech structure */
00240       return NULL;
00241    }
00242 
00243    /* Initialize the lock */
00244    ast_mutex_init(&new_speech->lock);
00245 
00246    /* Make sure no results are present */
00247    new_speech->results = NULL;
00248 
00249    /* Copy over our engine pointer */
00250    new_speech->engine = engine;
00251 
00252    /* We are not ready to accept audio yet */
00253    ast_speech_change_state(new_speech, AST_SPEECH_STATE_NOT_READY);
00254 
00255    /* Pass ourselves to the engine so they can set us up some more and if they error out then do not create a structure */
00256    if (engine->create(new_speech)) {
00257       ast_mutex_destroy(&new_speech->lock);
00258       free(new_speech);
00259       new_speech = NULL;
00260    }
00261 
00262    return new_speech;
00263 }

int ast_speech_register ( struct ast_speech_engine engine  ) 

Register a speech recognition engine.

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

00327 {
00328    struct ast_speech_engine *existing_engine = NULL;
00329    int res = 0;
00330 
00331    existing_engine = find_engine(engine->name);
00332    if (existing_engine != NULL) {
00333       /* Engine already loaded */
00334       return -1;
00335    }
00336 
00337    if (option_verbose > 1)
00338       ast_verbose(VERBOSE_PREFIX_2 "Registered speech recognition engine '%s'\n", engine->name);
00339 
00340    /* Add to the engine linked list and make default if needed */
00341    AST_LIST_LOCK(&engines);
00342    AST_LIST_INSERT_HEAD(&engines, engine, list);
00343    if (default_engine == NULL) {
00344       default_engine = engine;
00345       if (option_verbose > 1)
00346          ast_verbose(VERBOSE_PREFIX_2 "Made '%s' the default speech recognition engine\n", engine->name);
00347    }
00348    AST_LIST_UNLOCK(&engines);
00349 
00350    return res;
00351 }

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, 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, and ast_speech_engine::get.

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_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 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    ast_clear_flag(speech, AST_SPEECH_HAVE_RESULTS);
00164 
00165    /* If results are on the structure, free them since we are starting again */
00166    if (speech->results != NULL) {
00167       ast_speech_results_free(speech->results);
00168       speech->results = NULL;
00169    }
00170 
00171    /* If the engine needs to start stuff up, do it */
00172    if (speech->engine->start != NULL) {
00173       speech->engine->start(speech);
00174    }
00175 
00176    return;
00177 }

int ast_speech_unregister ( char *  engine_name  ) 

Unregister a speech recognition engine.

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

00355 {
00356    struct ast_speech_engine *engine = NULL;
00357    int res = -1;
00358 
00359    if (engine_name == NULL) {
00360       return res;
00361    }
00362 
00363    AST_LIST_LOCK(&engines);
00364    AST_LIST_TRAVERSE_SAFE_BEGIN(&engines, engine, list) {
00365       if (!strcasecmp(engine->name, engine_name)) {
00366          /* We have our engine... removed it */
00367          AST_LIST_REMOVE_CURRENT(&engines, list);
00368          /* If this was the default engine, we need to pick a new one */
00369          if (default_engine == engine) {
00370             default_engine = AST_LIST_FIRST(&engines);
00371          }
00372          if (option_verbose > 1)
00373             ast_verbose(VERBOSE_PREFIX_2 "Unregistered speech recognition engine '%s'\n", engine_name);
00374          /* All went well */
00375          res = 0;
00376          break;
00377       }
00378    }
00379    AST_LIST_TRAVERSE_SAFE_END
00380    AST_LIST_UNLOCK(&engines);
00381 
00382    return res;
00383 }

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

Write audio to the speech engine.

Definition at line 180 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().

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

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

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 391 of file res_speech.c.

References AST_LIST_HEAD_INIT_NOLOCK.

00392 {
00393    int res = 0;
00394 
00395    /* Initialize our list of engines */
00396    AST_LIST_HEAD_INIT_NOLOCK(&engines);
00397 
00398    return res;
00399 }

static int unload_module ( void   )  [static]

Definition at line 385 of file res_speech.c.

00386 {
00387    /* We can not be unloaded */
00388    return -1;
00389 }


Variable Documentation

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

Definition at line 404 of file res_speech.c.

const struct ast_module_info* ast_module_info = &__mod_info [static]

Definition at line 404 of file res_speech.c.

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 Sat Aug 6 00:40:04 2011 for Asterisk - the Open Source PBX by  doxygen 1.4.7