Adding a conversation module

To add a new conversation module, create a new instance of the conversation module interface (asr_conversation_if), which provides the communication mechanism between your new module and ASR. You must implement the following callback functions, which ASR invokes via the conversation module interface:

init()—initializes the module; invoked by asr_module_initialize().
select_result()—allows modules to accept a recognition result. ASR calls select_result() for the current exclusive module if there is one; otherwise, it makes the call for all active registered modules. Each module examines the list of results containing the hypotheses from the current recognition to determine the one it can successfully take action on, and then returns its selection via a result pointer. If there's no exclusive module, the selected result with the highest confidence level is used.
on_result()—handles the selected result. The module takes the appropriate action on the result (for example, invoking an application, dialing a phone number, or reprompting) and returns the next action ASR should take (see asr_result_action_t for the list of actions).
ASR calls on_result() for a module only if no other module has a result with a higher confidence level. ASR selects the module that provides the highest rating and sends it the current result for processing. The module can optionally set itself as exclusive by calling the asrm_set_exclusive() function so that it will receive all future results in the current speech session (i.e., io-asr won't evaluate the ratings of other conversation modules). The module releases its exclusive status when ASR transitions to the ASR_STEP_SESSION_CLOSED state.
stop()—for interrupting an action. This function provides a mechanism to interrupt an action and to allow ASR to recover gracefully.

Modules are loaded as DLLs at runtime. You must define a constructor function (designated with the ((constructor)) compiler attribute) that is called when ASR loads your module. This constructor function must call asrm_connect() to connect to io-asr and obtain your module's handle. The following code fragment illustrates this procedure for the dialer module:

typedef struct CarDialer_data_s {
    asr_module_hdl_t*    handle ;
    ...
}CarDialer_data _dialer_data ;

static const asr_conversation_if_t
CarDialer_interface = {
    .name           = "dialer",
    .asr_version    = ASR_VERSION,
    .init           = CarDialer_init,
    .destroy        = CarDialer_destroy,
    .on_asr_step    = CarDialer_step,
    .select_result  = CarDialer_selectResult,
    .on_result      = CarDialer_onResult,
} ;

__attribute__((constructor))
static void
CarDialer_register( void )
{
    CarDialer_data* self = &_dialer_data ;
    asr_module_hdl_t* module_handle ;

    memset( self, 0, sizeof( *self ) ) ;
    module_handle = asrm_connect( &CarDialer_interface, sizeof( CarDialer_interface ), self ) ;
    if ( self && module_handle ) {
            self->handle = module_handle ;
}
}

Note: In this example, the self data pointer is associated with the module. The io-asr service passes this pointer to all the module's callbacks as void* arguments. The pointer is then cast to the proper structure type to provide access to the module-specific data.

When ASR unloads the conversation module, it calls the module's destroy() callback function. This function should clean up any resources that were allocated in the init() function.