# Universal Speech Access API events

In response to commands executed by an application, USAI generates events and reason codes that indicate the occurrence (or lack) of certain conditions or state changes.

This topic provides the following information:

- NaturalAccess event structure

- Universal Speech Access API event header

- Alphabetical event summary

- Numerical event summary

- Event information buffers

## NaturalAccess event structure

Events returned by NaturalAccess APIs (such as USAI) conform to the following structure:

typedef struct
{
DWORD id;
CTAHD ctahd;
DWORD timestamp;
DWORD userid;
DWORD size;
void *buffer;
DWORD value;
unsigned objHd;
} CTA_EVENT;

where fields in the event structure provide the following information:

Field | Description
id | Event code (and source service id).
ctahd | NaturalAccess context handle.
timestamp | Timestamp associated with the event.
userid | User id defined by a call to ctaCreateContext.
size | Size of buffer if buffer, if applicable.
buffer | Pointer to a buffer location containing additional information associated with a the event
value | Event status information or event-specific data.
objHd | Service object handle.

USAI events are preceded with the prefix SAIEVN_ and contain. All defined SAI event buffers contain event header information and may contain additional information in the event buffer.

## Universal Speech Access API event header

Universal Speech Access API events contain the following header:

typedef struct
{
DWORD size; /* For compatibility. */
DWORD eventType; /* Event type */
SAI_REQUEST_ID reqId; /* Request id associated to this event */
SAI_REQUEST_STATE reqState; /* Command request state */
DWORD engineHandle; /* SAI_SYNTHESIZER_HANDLE or SAI_RECOGNIZER_HANDLE */
DWORD clientObjId; /* The client registered object identifier */
}
SAI_EVENT_HEADER;

The USAI event header provides the following information:

Field | Description
size | Size of the structure.
eventType | Type of event.
reqId | Request ID (requestId) associated with the event.
reqState | State of the command request associated with the event. Valid states: In-progress Pending Complete
engineHandle | Type of resource engine to which the request was directed. Valid engine types: SAI_SYNTHESIZER_HANDLE SAI_RECOGNIZER_HANDLE
clientObjId | Client registered object identifier.

## Alphabetical listing

The following table alphabetically lists the USAI events:

Event name | Description
SAIEVN_ASR_DEFINE_GRAMMAR_DONE | saiDefineGrammarRecognizer request was processed. The result of the request is returned in the statusCode field of the event buffer. Returns additional information in a SAI_EVENT_ASR_DEFINE_GRAMMAR buffer.
SAIEVN_ASR_GET_RESULT_DONE | saiGetResultRecognizer request was processed. The result of the request is returned in the statusCode field of the event buffer. Returns additional information in a SAI_EVENT_ASR_GET_RECOGNITION_RESULT buffer.
SAIEVN_ASR_RECOGNITION_DONE | saiStartRecognizer request is complete. The completion cause is provided in the completionCause field of the event buffer. Returns additional information in a SAI_EVENT_ASR_RECOGNITION_COMPLETE buffer.
SAIEVN_ASR_RECOGNITION_STARTED | Request to start the recognizer with saiStartRecognizer is currently in process. Returns additional information in a SAI_EVENT_COMMON buffer.
SAIEVN_ASR_START_OF_SPEECH | Recognizer detected speech input. Returns additional information in a SAI_EVENT_ASR_START_OF_SPEECH buffer.
SAIEVN_ASR_START_TIMER_DONE | saiStartTimerRecognizer request was processed. The result of the request is returned in the statusCode field of the event buffer. Returns additional information in a SAI_EVENT_COMMON buffer.
SAIEVN_ASR_STOP_DONE | saiStopRecognizer request was processed. The result of the request is returned in the statusCode field of the event buffer. Returns additional information in a SAI_EVENT_ASR_STOP buffer.
SAIEVN_ENGINE_CREATION_DONE | saiCreateRecognizer or saiCreateSynthesizer completed. The success or failure of the operation is indicated in the statusCode field of the event buffer. If the command completed successfully (the status code is SAI_SC_SUCCESS), the application can use the returned handle (recogHd or synthHd). If the operation failed, the application must call saiReleaseRecognizer or saiReleaseSynthesizer to release the returned handle. Returns additional information in a SAI_EVENT_ENGINE_CREATION buffer.
SAIEVN_ENGINE_RELEASE_DONE | USAI released the specified recognizer or synthesizer engine. Returns additional information in a SAI_EVENT_ENGINE_RELEASE buffer.
SAIEVN_ENGINE_FAILED | The connection to a TTS or ASR engine has failed. returns additional information in a SAI_EVENT_ENGINE_FAILED buffer.
SAIEVN_GET_PARAMETER_DONE | saiGetParamRecognizer or saiGetParamSynthesizer request was processed. The result of the request is returned in the statusCode field of the event buffer. Returns additional information in a SAI_EVENT_COMMON buffer.
SAIEVN_LINK_CHANGED | A state change occurred at the speech server network connection. The current connection state result is indicated by the isUp field of the SAI_EVENT_LINK_CHANGED event buffer.
SAIEVN_SET_PARAMETER_DONE | saiSetParamRecognizer or saiSetParamSynthesizer request was processed. The result of the request is returned in the statusCode field of the event buffer. Returns additional information in a SAI_EVENT_COMMON buffer.
SAIEVN_START_OF_SPEECH | Speech synthesizer process has begun.
SAIEVN_TTS_CONTROL_DONE | saiControlSynthesizer request was processed. The result of the request is returned in the statusCode field of the event buffer. Returns additional information in a SAI_EVENT_TTS_CONTROL buffer.
SAIEVN_TTS_NOTIFY_BARGE_IN_DONE | saiNotifyBargeInToSynthesizer request was processed. The result of the request is returned in the statusCode field of the event buffer. Returns additional information in a SAI_EVENT_TTS_NOTIFY_BARGE_IN buffer.
SAIEVN_TTS_PAUSE_DONE | saiPauseSynthesizer request was processed. The result of the request is returned in the statusCode field of the event buffer. Returns additional information in a SAI_EVENT_TTS_PAUSE buffer.
SAIEVN_TTS_RESUME_DONE | saiPauseSynthesizer request was processed. The result of the request is returned in the statusCode field of the event buffer. Returns additional information in a SAI_EVENT_TTS_RESUME buffer.
SAIEVN_TTS_SPEAK_ACKNOWLEDGED | saiPauseSynthesizer request was accepted and is being processed. The status code is indicated in the statusCode field of the event buffer. Returns additional information in a SAI_EVENT_COMMON buffer.
SAIEVN_TTS_SPEAK_DONE | When a speech server processes saiSpeakSynthesizer, this event indicates that the request is completed. The completion cause is returned in the completionCause field of the event buffer. Returns additional information in a SAI_EVENT_TTS_SPEAK_COMPLETE buffer.
SAIEVN_TTS_SPEAK_MARKER_REACHED | Unsolicited event that may be returned by the synthesizer when markers are included in the speech data specified with saiSpeakSynthesizer. The marker is returned in the event buffer. Retruns additional information in a SAI_EVENT_TTS_MARKER buffer.
SAIEVN_TTS_STOP_DONE | saiStopSynthesizer request was processed. The result of the request is returned in the statusCode field of the event buffer. Returns additional information in a SAI_EVENT_TTS_STOP buffer. Returns additional information in a SAI_EVENT_COMMON buffer.

## Numerical listing

The following table numerically lists the USAI events:

Hex | Decimal | Event name
0x322001 | 3284993 | SAIEVN_ENGINE_CREATION_DONE
0x322002 | 3284994 | SAIEVN_ENGINE_RELEASE_DONE
0x322003 | 3284995 | SAIEVN_GET_PARAMETER_DONE
0x322004 | 3284996 | SAIEVN_SET_PARAMETER_DONE
0x322005 | 3284997 | SAIEVN_ASR_DEFINE_GRAMMAR_DONE
0x322006 | 3284998 | SAIEVN_ASR_RECOGNITION_STARTED
0x322007 | 3284999 | SAIEVN_ASR_START_OF_SPEECH
0x322008 | 3285000 | SAIEVN_ASR_RECOGNITION_DONE
0x322009 | 3285001 | SAIEVN_ASR_STOP_DONE
0x32200A | 3285002 | SAIEVN_ASR_GET_RESULT_DONE
0x32200B | 3285003 | SAIEVN_ASR_START_TIMER_DONE
0x32200C | 3285004 | SAIEVN_TTS_SPEAK_ACKNOWLEDGED
0x32200D | 3285005 | SAIEVN_TTS_SPEAK_MARKER_REACHED
0x32200E | 3285006 | SAIEVN_TTS_SPEAK_DONE
0x32200F | 3285007 | SAIEVN_TTS_STOP_DONE
0x322010 | 3285008 | SAIEVN_TTS_PAUSE_DONE
0x322011 | 3285009 | SAIEVN_TTS_RESUME_DONE
0x322012 | 3285010 | SAIEVN_TTS_CONTROL_DONE
0x322013 | 3285011 | SAIEVN_TTS_NOTIFY_BARGE_IN_DONE
0x322014 | 3285012 | SAIEVN_ENGINE_FAILED

## Event information buffers

USAI events can return additional information in the following event buffers:

- SAI_EVENT_ASR_DEFINE_GRAMMAR

- SAI_EVENT_ASR_GET_RECOGNITION_RESULT

- SAI_EVENT_ASR_RECOGNITION_COMPLETE

- SAI_EVENT_ASR_START_OF_SPEECH

- SAI_EVENT_ASR_STOP

- SAI_EVENT_COMMON

- SAI_EVENT_ENGINE_CREATION

- SAI_EVENT_ENGINE_FAILED

- SAI_EVENT_ENGINE_RELEASE

- SAI_EVENT_LINK_CHANGED

- SAI_EVENT_TTS_CONTROL

- SAI_EVENT_TTS_MARKER

- SAI_EVENT_TTS_NOTIFY_BARGE_IN

- SAI_EVENT_TTS_PAUSE

- SAI_EVENT_TTS_RESUME

- SAI_EVENT_TTS_SPEAK_COMPLETE

- SAI_EVENT_TTS_STOP

### SAI_EVENT_ASR_DEFINE_GRAMMAR

Buffer associated with the SAIEVN_ASR_DEFINE_GRAMMAR_DONE event that is returned when an ASR engine finishes downloading and compiling a specified grammar. The SAI_EVENT_ASR_DEFINE_GRAMMAR buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER header;
SAI_STATUS_CODE statusCode;
SAI_RECOGNIZER_COMPLETION_CAUSE completionCause;
} SAI_EVENT_ASR_DEFINE_GRAMMAR;

where:

Field | Description
header | Event header.
statusCode | Status code that specifies result of the command by indicating the RTSP status code at the session establishment layer.
completionCause | Command completion cause

### SAI_EVENT_ASR_GET_RECOGNITION_RESULT

Buffer associated with the SAIEVN_ASR_GET_RESULT_DONE event that is returned when a request to re-compute a recognition process completes. The SAI_EVENT_ASR_GET_RECOGNITION_RESULT buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER header;
SAI_STATUS_CODE statusCode;
char recognitionResult[1];
} SAI_EVENT_ASR_GET_RECOGNITION_RESULT;

where:

Field | Description
header | Event header.
statusCode | Status code that specifies result of the command by indicating the RTSP status code at the session establishment layer.
recognitionResult | Pointer to the beginning of a string that provides the recognition result. Note: recognitionResult is always the last element in this structure. Do not use the size of this structure to determine the size of the received structure because recognitionResult marks only the beginning of the recognition result.

### SAI_EVENT_ASR_RECOGNITION_COMPLETE

Buffer associated with the SAIEVN_ASR_RECOGNITION_DONE event that is returned when the ASR engine completes (successfully or unsuccessfully) a recognition task.

If the completionCause value is SAI_RCC_NORMAL, then the recognitionResult value is valid. All media servers must support the W3C Natural Language Semantics Markup Language (NLSML) as the default standard for returning recognition results to the client, and must also support the MIME-type application/x-nlsml. The ASR context keeps the result and the audio waveform input of the recognition task until USAI receives the next recognition request .

The SAI_EVENT_ASR_RECOGNITION_COMPLETE buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER header;
SAI_RECOGNIZER_COMPLETION_CAUSE completionCause;
char recognitionResult[1];
} SAI_EVENT_ASR_RECOGNITION_COMPLETE;

where:

Field | Description
header | Event header.
completionCause | Reason that the ASR engine completed the recognition task and sent the result.
recognitionResult | Result of the recognition task. The result format follows the nssml standard. For example: Content-Type: application/x-nlsml Content-Length: 104 <?xml version="1.0"?> <result grammar="http://theYesNoGrammar> <interpretation> <instance> <myApp:yes_no> <response>yes</response> </myApp:yes_no> </instance> <input>ok</input> </interpretation> </result> Note: recognitionResult is always the last element of the structure. Do not use the size of this structure to determine the size of the received structure because recognitionResult marks only the beginning of the recognition result.

### SAI_EVENT_ASR_START_OF_SPEECH

Buffer associated to the SAIEVN_ASR_START_OF_SPEECH event that is returned when the ASR engine detects a speech signal. The SAIEVN_ASR_START_OF_SPEECH event is useful in implementing kill-on-barge-in functionality when the synthesizer resource is in a different session than the recognizer resource and therefore is not aware of an incoming audio source. In these cases, the client must act as a proxy and invoke saiNotifyBargeInToSynthesizer to notify the synthesizer that a barge-in occurred.

The recognizer resource returns a unique proxy-sync-id in the event header, according to the proxySyncId parameter specified in saiNotifyBargeInToSynthesizer.

The SAI_EVENT_ASR_START_OF_SPEECH buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER header;
SAI_PROXY_SYNC_ID proxySyncId;
} SAI_EVENT_ASR_START_OF_SPEECH;

where:

Field | Description
header | Event header.
proxySyncId | A unique identifier generated by saiNotifyBargeInToSynthesizer and returned by the ASR engine. When the recognizer and synthesizer resources are part of the same session, they can work together to achieve quicker interaction and response times. In this case, the proxySyncId helps the resource that receives the event (the client acts as a proxy in transferring the event) to determine if the event was processed through a direct resource interaction.

### SAI_EVENT_ASR_STOP

Buffer associated with the SAIEVN_ASR_STOP_DONE event that is returned when a request to stop a recognition process completes. The SAIEVN_ASR_STOP_DONE buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER header;
SAI_STATUS_CODE statusCode;
SAI_REQUEST_ID stoppedReqId;
} SAI_EVENT_ASR_STOP;

where:

Field | Description
header | Event header.
statusCode | Status code that specifies result of the command by indicating the RTSP status code at the session establishment layer.
stoppedReqId | Request identifier of the recognition process associated with the stop command.

### SAI_EVENT_COMMON

Buffer associated to the following events:

- SAIEVN_GET_PARAMETER_DONE

- SAIEVN_SET_PARAMETER_DONE

- SAIEVN_ASR_RECOGNITION_STARTED

- SAIEVN_ASR_START_TIMER_DONE

- SAIEVN_TTS_SPEAK_ACKNOWLEDGED

- SAIEVN_ENGINE_FAILED

The SAI_EVENT_COMMON buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER header;
SAI_STATUS_CODE statusCode;
} SAI_EVENT_COMMON;

where:

Field | Description
header | Event header.
statusCode | Status code that specifies the result of the command. Indicates the RTSP status code at the session establishment layer.

### SAI_EVENT_ENGINE_CREATION

Buffer associated with the SAIEVN_ENGINE_CREATION_DONE event that indicates that USAI has either succeeded or failed in creating a TTS or ASR engine. The SAIEVN_ENGINE_CREATION buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER header;
SAI_ENGINE_STATUS_CODE statusCode;
DWORD enginePort;/
char engineIp[SAI_MAX_IP_ADDRESS_LENGTH];
} SAI_EVENT_ENGINE_CREATION;

where:

Field | Description
header | Event header.
statusCode | Status code defining the result of the command. Indicates the RTSP status code at the session establishment layer.
enginePort | Engine RTP port.
engineIp | IP address of the speech server.

### SAI_EVENT_ENGINE_FAILED

Buffer associated with the SAIEVN_ENGINE_FAILED event returned when a session connection problem occured at the TTS or ASR side. When an application receives an SAIEVN_ENGINE_FAILED event, it must invoke saiReleaseSynthesizer or saiReleaseRecognizer to release the associated TTS or ASR engine.

The SAI_EVENT_ENGINE_FAILED buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER header;
SAI_ENGINE_STATUS_CODE statusCode;
} SAI_EVENT_ENGINE_FAILED;

where:

Field | Description
header | Event header.
statusCode | Status code defining the result of the command. Indicates the RTSP status code at the session layer.

### SAI_EVENT_ENGINE_RELEASE

Buffer associated with the SAIEVN_ENGINE_RELEASE_DONE event. The buffer indicates whether the ASR or TTS engine has been released. The SAIEVN_ENGINE_CREATION buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER header;
SAI_ENGINE_STATUS_CODE statusCode;
} SAI_EVENT_ENGINE_RELEASE;

where:

Field | Description
header | Event header.
statusCode | Status code that indicating result of the command by specifying the RTSP status code at the session establishment layer.

### SAI_EVENT_LINK_CHANGED

Buffer associated with the SAIEVN_LINK_CHANGED event that indicates whether the speech server is up or down. The SAIEVN_LINK_CHANGED buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER header;
BOOL isUp;
char serverName[SAI_MAX_SERVER_NAME];
} SAI_EVENT_LINK_CHANGED;

where:

Field | Description
header | Event header.
isUp | Boolean value determining whether the speech server went down or is returned to service. Valid values include the following: 1 = UP 0 = DOWN
serverName | String that indicates the server where the connection went down or returned to service.

### SAI_EVENT_TTS_CONTROL

Buffer associated to the SAIEVN_TTS_CONTROL_DONE event that is returned when the a speech synthesis control request completes. The SAI_EVENT_TTS_CONTROL buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER header;
SAI_STATUS_CODE statusCode;
BOOL fSpeakRestart;
SAI_REQUEST_ID reqList[ SAI_MAX_STOPREQUEST + 1 ]; // +1 for padding
} SAI_EVENT_TTS_CONTROL;

where:

Field | Description
header | Event header.
statusCode | Command status code.
fSpeakRestart | Indicate if a jump backwards to the beginning of a segment of speech data has occurred.
reqList | The list of active request identifiers associated with the control command.

### SAI_EVENT_TTS_MARKER

Buffer associated with the unsolicited SAIEVN_TTS_SPEAK_MARKER_REACHED event that is returned when the TTS engine detects an occurrence of a specified marker. The SAI_EVENT_TTS_MARKER buffer consists of the following fields::

typedef struct
{
SAI_EVENT_HEADER header;
SAI_MARKER markerStr;
} SAI_EVENT_TTS_MARKER;

where:

Field | Description
header | Event header.
markerStr | String that indicates the marker that was reached.

### SAI_EVENT_TTS_NOTIFY_BARGE_IN

Buffer associated to the SAIEVN_TTS_NOTIFY_BARGE_IN_DONE event that is returned when a NOTIFY-BARGE-IN request completes. The SAI_EVENT_TTS_NOTIFY_BARGE_IN buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER header;
SAI_STATUS_CODE statusCode;
SAI_REQUEST_ID reqList[ SAI_MAX_STOPREQUEST + 1 ]; // +1 for padding
} SAI_EVENT_TTS_NOTIFY_BARGE_IN;

where:

Field | Description
header | Event header.
statusCode | Command status code
reqList | Array of SAI_REQUEST_IDs associated with speech synthesis requests to be terminated when the TTS engine receives the NOTIFY-BARGE-IN command.

### SAI_EVENT_TTS_PAUSE

Buffer associated to the SAIEVN_TTS_PAUSE_DONE event that is returned when a request to pause an active speech synthesis process completes. The SAI_EVENT_TTS_PAUSE buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER header;
SAI_STATUS_CODE statusCode;
SAI_REQUEST_ID pausedReqId; /* The paused reqId */
} SAI_EVENT_TTS_PAUSE;

where:

Field | Description
header | Event header.
statusCode | Command status code
pausedReqId | The request identifier of the paused speech synthesis process.

### SAI_EVENT_TTS_RESUME

Buffer associated to the SAIEVN_TTS_RESUME_DONE event that is returned when the request to resume a paused speech synthesis process completes. The SAI_EVENT_TTS_RESUME buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER header;
SAI_STATUS_CODE statusCode;
SAI_REQUEST_ID resumedReqId;
} SAI_EVENT_TTS_RESUME;

where:

Field | Description
header | Event header.
statusCode | Command status code
resumedReqId | The request identifier of the speech synthesis process to resume.

### SAI_EVENT_TTS_SPEAK_COMPLETE

Buffer associated with the SAIEVN_TTS_SPEAK_DONE event that is returned when the TTS engine successfully or unsuccessfully completes a speech synthesis command. The SAI_EVENT_TTS_SPEAK_COMPLETE buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER header;
SPEAK_COMPLETION_CAUSE completionCause;
} SAI_EVENT_TTS_SPEAK_COMPLETE;

where:

Field | Description
header | Event header.
completionCause | String that indicates the completion cause. Refer to SAI_SPEAK_COMPLETION_CAUSE for a list of possible causes.

### SAI_EVENT_TTS_STOP

Buffer associated to the SAIEVN_TTS_STOP_DONE event that is returned when a request to stop a list of speech synthesis tasks completes. The SAI_EVENT_TTS_STOP buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER header;
SAI_STATUS_CODE statusCode;
SAI_REQUEST_ID reqList[ SAI_MAX_STOPREQUEST + 1 ]; // +1 for padding
} SAI_EVENT_TTS_STOP;

where:

Field | Description
header | Event header.
statusCode | Command status code
reqList | Array containing the request identifiers of all pending speech synthesis requests to be terminated by the stop command.