# saiStartRecognizer

Activates a recognition process.

#### Prototype

DWORD saiStartRecognizer ( SAI_RECOGNIZER_HANDLE recog Hd, SAI_GRAMMAR_TYPE grmType, void *data, SAI_REQUEST_ID *requestId )

Argument | Description
recogHd | Handle associated with a recognizer resource.
grmType | List of pre-defined grammar sets. The following list shows string and decimal values for supported grammar types: SAI_GRAMMAR_TYPE_URL [0]: The grammar includes a URL that is loaded by the recognizer engine. SAI_GRAMMAR_TYPE_XML [1]: The grammar is formatted following XML rules. SAI_GRAMMAR_TYPE_GRAMMAR_LIST [2]: The grammar is a list in table form.
data | Pointer to the grammar payload. This can be the grammar list previously defined.
requestId | Pointer to a unique request identifier returned for this command.

#### Return values

Return value | Description
SUCCESS |
SAIERR_ENGINE_NOT_READY | Specified recognizer engine is not ready to handle requests.
SAIERR_INVALID_PARAMETER | One of the specified arguments is invalid.
SAIERR_LIST_EMPTY | Grammar list referenced by data contains no entries.
SAIERR_LIST_NOT_INITIALIZED | Grammar list referenced by data was not initialized with saiInitRecognitionList.

#### Events

Event | Description
SAIEVN_ASR_RECOGNITION_DONE | Request is complete. The completion cause is provided in the completionCause field of the SAIEVN_ASR_RECOGNITION_DONE event buffer.
SAIEVN_ASR_RECOGNITION_STARTED | Recognizer start request is currently in process.
SAIEVN_START_OF_SPEECH | Unsolicited event indicating that the speech synthesizer process has begun.

#### Details

saiStartRecognizer requests that the recognizer begin performing speech recognition of a stream of voice data and provides the grammar to use (in the data argument) when performing this process. If the specified grmType is SAI_GRAMMAR_TYPE_GRAMMAR_LIST, data contains a previously compiled list of grammar names. When invoking saiStartRecognizer, the application can specify parameters that control the following aspects of recognizer processing:

- Sensitivity

- Confidence level

- Level of detail in results generated by the recognizer

Parameters that the application specifies when invoking saiStartRecognizer override parameter settings established by a previous call to saiSetParamRecognizer. However, the parameter values revert to their initial values when the SAI service returns SAIEVN_ASR_RECOGNITION_DONE.

For more information, refer to Creating a recognition grammar.

#### See also

saiAddRecognitionGrammar, saiDefineGrammarRecognizer, saiGetResultRecognizer, saiStopRecognizer

#### Example

//
// Start recognition with grammar list name. ASR handle is used to reach the appropriate
// recognition engine created previously.
// The Application waits on the event queue to receive the SAIEVN_ASR_RECOGNITION_STARTED and
// SAIEVN_ASR_RECOGNITION_DONE.
//
// Grammars are defined on server and can now be reached by URL path during the current speech
// session. With this function using grammar list names, grammar can actually be called with its
// corresponding name tag (enumerated in a grammar list name) and attributed when calling
// saiAddRecognitionGrammar.
//
DWORD demoAsrStartGrmListName( CTAQUEUEHD queueHd, SAI_RECOGNIZER_HANDLE asrHd )
{
DWORD rc = SUCCESS;
SAI_REQUEST_ID reqId = 0;
DWORD grmListSize = TEST_MAX_GRAMMAR_LIST_SIZE;
void* grmList = calloc( 1, grmListSize );
rc = saiInitRecognitionList( grmList, grmListSize );
if (rc == SUCCESS)
{
rc = saiAddRecognitionGrammar(grmList, SAI_GRAMMAR_TYPE_XML, "grammar1",
G_speech_digit_grammar_enUS );
}
if (rc == SUCCESS)
{
//
// Upload the grammar for compilation on server
//
rc = saiDefineGrammarRecognizer( asrHd, grmList, "myDefinedGrammar", &reqId );
}
if ( rc == SUCCESS )
{
//
// Verify each event received in queue as long as the appropriate one
// (in this case: SAIEVN_ASR_DEFINE_GRAMMAR_DONE) are received or before
// timeout is over. Verify that status code and reqId are the same as buffer memory.
//
rc = demoWaitForEventDefGramFcn(queueHd, reqId);
}
if ( rc == SUCCESS )
{
//
// Start recognition process using the grammar list that has been defined on server
// (so it becomes a recognition using URL type), reqId associated to the current
// request is returned.
//
SAI_URL urlListName[] = { {"myDefinedGrammar"},
{""}
};
rc = saiStartRecognizer(asrHd, SAI_GRAMMAR_TYPE_URL, urlListName, &reqId );
}
if ( rc == SUCCESS )
{
//
// Verify each event received in queue as long as the appropriate one
// (in this case: SAIEVN_ASR_RECOGNITION_STARTED and SAIEVN_ASR_RECOGNITION_DONE) are
// received or before timeout is over. Verify that status code, completion cause and
// reqId are the same as buffer memory.
//
rc = demoWaitForEventRecognitionFcn(queueHd, reqId);
}
if (rc == SUCCESS)
{
printf("Recognition with SAI_GRAMMAR_TYPE_URL(grammar list name) succeed!.\n");
}
else
{
printf("Recognition with SAI_GRAMMAR_TYPE_URL(grammar list name) failed, error code = 0x%08X.\n", rc);
}
return rc;
}