asr_conversation_if

Conversation module interface.

Synopsis:

struct asr_conversation_if asr_conversation_if_t {
    const char * name ;
    const char * asr_version ;
    int localized ;
    int(* init )(void *module_data, cfg_item_t *asr_config);
    void(* destroy )(void *module_data);
    int(* on_asr_step )(asr_step_t step, void *module_data);
    int(* select_result )(asr_result_t *results, void *module_data, asr_result_t **selected_result);
    asr_result_action_t(* on_result )(asr_result_t *result, asr_result_t *results, void *module_data);
    asr_result_action_t(* on_result_data )(void *result, void *module_data, int error);
    void(* stop )(void);
};

Data:

const char * name
The name of this module.
const char * asr_version
The version of ASR that this module was designed for.

The version number is used to prevent newer, incompatible modules from being used with an older build of ASR.

int localized
Indicates whether localized assets (TTS prompts, commands, etc.) are required.

Set to 0 if no localized assets are needed.

int(* init)(void *module_data, cfg_item_t *asr_config)
Initialize the specified module.

Optional. The io-asr service calls init() for each registered module upon startup.

Arguments
  • module_data The data provided to io-asr when the module registered itself.
  • asr_config Configuration information for the converstaion module.
Returns
  • 0 Success
  • -1 An error occurred. The io-asr service logs the error and exits.
void(* destroy)(void *module_data)
Destroy a module.

Optional. The io-asr service calls destroy() when shutting down a module that has successfuly initialized via the init() function.

Arguments
  • module_data The data provided to io-asr when the module registered itself.
int(* on_asr_step)(asr_step_t step, void *module_data)
Handle a change of state.

Optional. The io-asr service calls on_asr_step() each time the state of the recognizer changes (see asr_step_t).

Arguments
  • step The current or last event that occurred on the recognizer.
  • module_data The data provided to io-asr when the module registered itself.
Returns
  • 0 Success.
  • -1 An error occurred. The io-asr service logs the error and exits.
int(* select_result)(asr_result_t *results, void *module_data, asr_result_t **selected_result)
Select a recognition result from active modules.

Optional. The io-asr service calls select_result() for the current exclusive module if there is one; otherwise, io-asr makes the call for all active registered modules. If a result is selected, it is returned via selected_result.

Arguments
  • results A list of results containing the hypotheses from the current recognition.
  • module_data The data provided to io-asr when the module registered itself.
  • selected_result A pointer to the result most suited for the module. The io-asr service treats as valid any result with a return value greater than -1.
Returns
  • > -1 if a result is selected; -1 if no result is selected.
asr_result_action_t(* on_result)(asr_result_t *result, asr_result_t *results, void *module_data)
Handle a selected result.

Optional. The io-asr service calls on_result() for a module only if no other module has a result with a higher confidence level. Results found to be relevant to this module won't be processed if this function isn't defined.

Arguments
  • result A reference to the selected result within the results list.
  • results The full list of results.
  • module_data The data provided to io-asr when the module registered itself.
Returns
  • The next action to take. See asr_result_action_t for the list of actions.
asr_result_action_t(* on_result_data)(void *result, void *module_data, int error)
Pass additional data for use with a result.

Optional. The io-asr service calls on_result_data() to specify additional parameters or pass additional data that the module requires (i.e., not recognition results). For example, the module may require a vendor-specific data format (e.g., a tracklist generated from a find music command).

Arguments
  • module_data The data or parameters to be passed to the module.
  • error An error code. The error value is currently specific to the ASR vendor used with io-asr.
Returns
  • The next action to take; NULL on error. See asr_result_action_t for the list of actions.
void(* stop)(void)
Stop the module.

Optional. The io-asr service calls stop() if the speech session is canceled before an on_result() callback has completed. This callback can be useful to break out of any function that blocks for an extended period of time in the on_result() callback. A new speech session can't be started until the on_result() callback returns.

Library:

libasr

Description:

This structure defines the interface from io-asr to the conversation modules. Each conversation module's constructor function passes this structure to the asrm_connect() function. The io-asr service invokes the member callback functions depending on the state of the module.