# Application Programming Interface (API) Reference

# Reply Message Structures and Callbacks

The information in this chapter describes reply structures and callbacks.

## Reply Message Structures Received from the Speech Engine

An application can receive the following reply message structures, defined in SMCOMM.H, from the speech engine.

Reply message structures received by the application that are not in response to an API call request are termed unsolicited.

Reply Message Structure | Solicited | Unsolicited | Explanation
--- | --- | --- | ---
SM_ADD_PRONUNCIATION_REPLY | X |  | Response to an asynchronous SmAddPronunciation call. Data can be extracted with SmGetSpelling or SmGetSpellings.
SM_ADD_TO_VOCAB_REPLY | X |  | Response to an asynchronous SmAddToVocab call. Data can be extracted with SmGetVocabName or SmGetVocWords.
SM_AUDIO_LEVEL |  | X | Controlled by SmSet SM_NOTIFY_AUDIO_LEVEL, this message provides the audio level data. Data can be extracted with SmGetAudioLevel.
SM_CANCEL_PLAYBACK_REPLY | X |  | Response to an asynchronous SmCancelPlayback call.
SM_COMMAND_WORD |  | X | Controlled by SmSet SM_NOTIFY_COMMAND_WORD, this message provides the name of the application that currently has focus as well as the last recognized input word. The SmGetFirmWords function extracts the SM_WORD and the SmGetApplication function extracts the application name.
SM_CONNECT_REPLY | X |  | Response to an asynchronous SmConnect call. Data can be extracted with SmGetEnrollId, SmGetEnrollIds, SmGetLanguages, SmGetMsgType, SmGetService, SmGetSessionId, SmGetTask, SmGetTasks, SmGetUserId, or SmGetUserIds.
SM_CORRECT_TEXT_CANCEL_REPLY | X |  | Response to an asynchronous SmCorrectTextCancel call.
SM_CORRECT_TEXT_REPLY | X |  | Response to an asynchronous SmCorrectText call.
SM_DEFINE_GRAMMAR_REPLY | X |  | Response to an asynchronous SmDefineGrammar call.
SM_DEFINE_VOCAB_REPLY | X |  | Response to an asynchronous SmDefineVocab call. Data can be extracted with SmGetVocabName or SmGetVocWords.
SM_DETACH_SESSIONS_REPLY | X |  | Response to an asynchronous SmDetachSessions call.
SM_DISABLE_VOCAB_REPLY | X |  | Response to an asynchronous SmDisableVocab call. Data can be extracted with SmGetVocabName.
SM_DISCARD_DATA_REPLY | X |  | Response to an asynchronous SmDiscardData call.
SM_DISCONNECT_REPLY | X |  | Response to an asynchronous SmDisconnect call. Data can be extracted with SmGetMsgType, or SmGetService.
SM_ENABLE_VOCAB_REPLY | X |  | Response to an asynchronous SmEnableVocab call. Data can be extracted with SmGetVocabName.
SM_ENGINE_STATE |  | X | Controlled by SmSet SM_NOTIFY_ENGINE_STATE, this message indicates current engine status and synchronizes the display and the engine state. The SmGetEngineState function extracts the data.
SM_EVENT_NOTIFY_REPLY | X |  | Response to an asynchronous SmEventNotify call. Data can be extracted with SmGetEventId.
SM_EVENT_SYNCH |  | X | Notification of an occurrence of event specified in previous SmEventNotify. Data can be extracted with SmGetEventId or SmGetEventOptions.
SM_FOCUS_GRANTED |  | X | Asynchronous notification of focus granted. Data can be extracted with SmGetMicState.
SM_FOCUS_LOST |  | X | Asynchronous notification of focus lost.
SM_FOCUS_STATE |  | X | Controlled by SmSet SM_NOTIFY_FOCUS_STATE, this message shows a change in focus status and includes the name of the associated application. The SmGetFocusState function extracts the focus state and the SmGetApplication function extracts the application name.
SM_HALT_RECOGNIZER_REPLY | X |  | Response to an asynchronous SmHaltRecognizer call. Data can be extracted with SmGetNumberWordMsgs.
SM_MIC_OFF_REPLY | X |  | Response to an asynchronous SmMicOff call.
SM_MIC_ON_REPLY | X |  | Response to an asynchronous SmMicOn call. Data can be extracted with SmGetUtteranceNumber.
SM_MIC_OFF_REQUESTED |  | X | Request to turn off the microphone.
SM_MIC_ON_REQUESTED |  | X | Request to turn on the microphone.
SM_MIC_STATE |  | X | Controlled by SmSet SM_NOTIFY_MIC_STATE, this message indicated whether the microphone is on or off. Data can be extracted with SmGetMicState.
SM_NEW_CONTEXT_REPLY | X |  | Response to an asynchronous SmNewContext call.
SM_PLAY_MESSAGE_REPLY | X |  | Response to an asynchronous SmPlayMessage call. Assuming a successful call, SM_PLAY_MESSAGE_STATUS reply message structures will follow.
SM_PLAY_MESSAGE_STATUS |  | X | Notification of the start and completion of the audio playback initiated by an SmPlayMessage call. Data can be extracted with SmGetMsgName or SmGetStatus.
SM_PLAY_UTTERANCE_REPLY | X |  | Response to an asynchronous SmPlayUtterance call. Assuming a successful call, SM_PLAY_UTTERANCE_STATUS reply message structures will follow.
SM_PLAY_UTTERANCE_STATUS |  | X | Notification of the start and completion of the audio playback initiated by an SmPlayUtterance call. Data can be extracted with SmGetStatus or SmGetUtteranceNumber.
SM_PLAY_WORDS_REPLY | X |  | Response to an asynchronous SmPlayWords call. Assuming a successful call, SM_PLAY_WORDS_STATUS reply message structures will follow.
SM_PLAY_WORDS_STATUS |  | X | Notification of the start and completion of the audio playback initiated by an SmPlayWords call. Audio playback may be for one word or multiple words. Data can be extracted with SmGetStatus or SmGetTags.
SM_QUERY_ADDED_WORDS_REPLY | X |  | Response to an asynchronous SmQueryAddedWords call. Data can be extracted with SmGetWords.
SM_QUERY_ALTERNATES_REPLY | X |  | Response to an asynchronous SmQueryAlternates call. Data can be extracted with SmGetAlternates or SmGetTags.
SM_QUERY_DEFAULT_REPLY | X |  | Response to an asynchronous SmQueryDefault call. Data can be extracted with SmGetEnrollId, SmGetEnrollIds, SmGetScripts, SmGetTask, SmGetTasks, SmGetUserId or SmGetUserIds.
SM_QUERY_ENABLED_VOCABS_REPLY | X |  | Response to an asynchronous SmQueryEnabledVocabs call. Data can be extracted with SmGetVocabList.
SM_QUERY_ENROLLIDS_REPLY | X |  | Response to an asynchronous SmQueryEnrollIds call. Data can be extracted with SmGetAlphabets, SmGetDescriptions, SmGetEnrollIds, SmGetLanguages, SmGetPercentages, SmGetScripts, or SmGetStates.
SM_QUERY_LANGUAGES_REPLY | X |  | Response to an asynchronous SmQueryLanguages call. Data can be extracted with SmGetLanguages.
SM_QUERY_PRONUNCIATION_REPLY | X |  | Response to an asynchronous SmQueryPronunciation call. Data can be extracted with SmGetSpelling or SmGetSpellings.
SM_QUERY_PRONUNCIATIONS_REPLY | X |  | Response to an asynchronous SmQueryPronunciations call. Data can be extracted with SmGetPronunciations or SmGetSpellings.
SM_QUERY_REPLY | X |  | Response to an asynchronous SmQuery call. Data can be extracted with SmGetItemValue.
SM_QUERY_SESSIONS_REPLY | X |  | Response to an asynchronous SmQuerySessions call. Data can be extracted with SmGetApplications, SmGetEnrollIds, or SmGetUserIds.
SM_QUERY_SPEECH_DATA_REPLY | X |  | Response to an asynchronous SmQuerySpeechData call.
SM_QUERY_TASKS_REPLY | X |  | Response to an asynchronous SmQueryTasks call. Data can be extracted with SmGetAlphabets, SmGetDescriptions, SmGetLanguages or SmGetTasks.
SM_QUERY_USER_INFO_REPLY | X |  | Response to an asynchronous SmQueryUserInfo call. Data can be extracted with SmGetEnrollId, SmGetEnrollIds, SmGetNameValue, SmGetUserId, or SmGetUserIds.
SM_QUERY_USERS_REPLY | X |  | Response to an asynchronous SmQueryUsers call. Data can be extracted with SmGetDescriptions, SmGetUserIds, or SmGetUsers.
SM_QUERY_VOCABS_REPLY | X |  | Response to an asynchronous SmQueryVocabs call. Data can be extracted with SmGetVocabList.
SM_QUERY_WORD_REPLY | X |  | Response to an asynchronous SmQueryWord call. Data can be extracted with SmGetVocabList or SmGetWords.
SM_RECOGNIZED_PHRASE |  | X | Includes firm words sent during grammar vocabulary recognition. Data can be extracted with SmGetFirmWords, SmGetVocabName, SmGetPhraseState.
SM_RECOGNIZED_TEXT |  | X | Includes infirm or firm words or both sent during dictation vocabulary recognition. Data can be extracted with SmGetFirmWords, SmGetInfirmWords, or SmGetTimes.
SM_RECOGNIZED_WORD |  | X | Includes firm words sent during command vocabulary recognition. Data can be extracted with SmGetAlternates, SmGetFirmWords, or SmGetTimes.
SM_RECOGNIZE_NEXT_WORD_REPLY | X |  | Response to an asynchronous SmRecognizeNextWord call.
SM_RELEASE_FOCUS | X |  | Response to an asynchronous SmReleaseFocus call.
SM_REMOVE_FROM_VOCAB_REPLY | X |  | Response to an asynchronous SmRemoveFromVocab call. Data can be extracted with SmGetVocabName.
SM_REMOVE_PRONUNCIATION_REPLY | X |  | Response to an asynchronous SmRemovePronunciation call. Data can be extracted with SmGetSpelling or SmGetSpellings.
SM_REPORT_ENGINE_ERROR |  | X | Notification that the speech engine has encountered an error. Data can be extracted with SmGetMicState or SmGetSeverity.
SM_REQUEST_DETACH |  | X | Request to detach sessions.
SM_REQUEST_FOCUS | X |  | Response to an asynchronous SmRequestFocus call.
SM_REQUEST_MIC_OFF_REPLY | X |  | Response to an asynchronous SmRequestMicOff call.
SM_REQUEST_MIC_ON_REPLY | X |  | Response to an asynchronous SmRequestMicOn call.
SM_RESTORE_SPEECH_DATA_REPLY | X |  | Response to an asynchronous SmRestoreSpeechData call.
SM_SAVE_SPEECH_DATA_REPLY | X |  | Response to an asynchronous SmSaveSpeechData call.
SM_SET_DEFAULT_REPLY | X |  | Response to an asynchronous SmSetDefault call.
SM_SET_REPLY | X |  | Response to an asynchronous SmSet call. Data can be extracted with SmGetItemValue.
SM_SET_USER_INFO_REPLY | X |  | Response to an asynchronous SmSetUserInfo call. Data can be extracted with SmGetEnrollId, SmGetEnrollIds, SmGetUserId or SmGetUserIds.
SM_UNDEFINE_VOCAB_REPLY | X |  | Response to an asynchronous SmUndefineVocab call. Data can be extracted with SmGetVocabName.
SM_UTTERANCE_COMPLETED |  | X | Notification that speech-to-text decoding of the audio input stream has been completed after the microphone was turned off. Data can be extracted with SmGetUtteranceNumber.
SM_WORD_CORRECTION_REPLY | X |  | Response to an asynchronous SmWordCorrection call. Data can be extracted with SmGetPronunciations, SmGetSpellings, SmGetStatus or SmGetTags.

## Callbacks

The following callbacks are available for processing messages from the router and the speech engine.

Callback | Solicited | Unsolicited | Message Type
--- | --- | --- | ---
SmNaddPronunciationCallback | X |  | SM_ADD_PRONUNCIATION_REPLY
SmNaddToVocabCallback | X |  | SM_ADD_TO_VOCAB_REPLY
SmNaudioLevelCallback |  | X | SM_AUDIO_LEVEL
SmNcancelPlaybackCallback | X |  | SM_CANCEL_PLAYBACK_REPLY
SmNcommandWordCallback |  | X | SM_COMMAND_WORD
SmNconnectCallback | X |  | SM_CONNECT_REPLY
SmNcorrectTextCallback | X |  | SM_CORRECT_TEXT_REPLY
SmNcorrectTextCancelCallback | X |  | SM_CORRECT_TEXT_CANCEL_REPLY
SmNdefineGrammarCallback | X |  | SM_DEFINE_GRAMMAR_REPLY
SmNdefineVocabCallback | X |  | SM_DEFINE_VOCAB_REPLY
SmNdetachRequestedCallback |  | X | SM_REQUEST_DETACH
SmNdetachSessionsCallback | X |  | SM_DETACH_SESSIONS_REPLY
SmNdisableVocabCallback | X |  | SM_DISABLE_VOCAB_REPLY
SmNdiscardDataCallback | X |  | SM_DISCARD_DATA_REPLY
SmNdisconnectCallback | X |  | SM_DISCONNECT_REPLY
SmNenableVocabCallback | X |  | SM_ENABLE_VOCAB_REPLY
SmNengineStateCallback |  | X | SM_ENGINE_STATE
SmNeventNotifyCallback | X |  | SM_EVENT_NOTIFY_REPLY
SmNeventSynchCallback |  | X | SM_EVENT_SYNCH
SmNfocusGrantedCallback |  | X | SM_FOCUS_GRANTED
SmNfocusLostCallback |  | X | SM_FOCUS_LOST
SmNfocusStateCallback |  | X | SM_FOCUS_STATE
SmNhaltRecognizerCallback | X |  | SM_HALT_RECOGNIZER_REPLY
SmNmicOffCallback | X |  | SM_MIC_OFF_REQUESTED
SmNmicOnCallback | X |  | SM_MIC_ON_REQUESTED
SmNmicOffRequestedCallback |  | X | SM_REQUEST_MIC_OFF_REPLY
SmNmicOnRequestedCallback |  | X | SM_REQUEST_MIC_ON_REPLY
SmNmicStateCallback |  | X | SM_MIC_STATE
SmNnewContextCallback | X |  | SM_NEW_CONTEXT_REPLY
SmNplayMessageCallback | X |  | SM_PLAY_MESSAGE_REPLY
SmNplayMessageStatusCallback |  | X | SM_PLAY_MESSAGE_STATUS
SmNplayUtteranceCallback | X |  | SM_PLAY_UTTERANCE_REPLY
SmNplayUtteranceStatusCallback |  | X | SM_PLAY_UTTERANCE_STATUS
SmNplayWordsCallback | X |  | SM_PLAY_WORDS_REPLY
SmNplayWordsStatusCallback |  | X | SM_PLAY_WORDS_STATUS
SmNqueryAddedWordsCallback | X |  | SM_QUERY_ADDED_WORDS_REPLY
SmNqueryAlternatesCallback | X |  | SM_QUERY_ALTERNATES_REPLY
SmNqueryCallback | X |  | SM_QUERY_REPLY
SmNqueryDefaultCallback | X |  | SM_QUERY_DEFAULT_REPLY
SmNqueryEnabledVocabsCallback | X |  | SM_QUERY_ENABLED_VOCABS_REPLY
SmNqueryEnrollIdsCallback | X |  | SM_QUERY_ENROLLIDS_REPLY
SmNqueryLanguagesCallback | X |  | SM_QUERY_LANGUAGES_REPLY
SmNqueryPronunciationCallback | X |  | SM_QUERY_PRONUNCIATION_REPLY
SmNqueryPronunciationsCallback | X |  | SM_QUERY_PRONUNCIATIONS_REPLY
SmNquerySessionsCallback | X |  | SM_QUERY_SESSIONS_REPLY
SmNquerySpeechDataCallback | X |  | SM_QUERY_SPEECH_DATA_REPLY
SmNqueryTasksCallback | X |  | SM_QUERY_TASKS_REPLY
SmNqueryUsersCallback | X |  | SM_QUERY_USERS_REPLY
SmNqueryUserInfoCallback | X |  | SM_QUERY_USER_INFO_REPLY
SmNqueryVocabsCallback | X |  | SM_QUERY_VOCABS_REPLY
SmNqueryWordCallback | X |  | SM_QUERY_WORD_REPLY
SmNrecognizeNextWordCallback | X |  | SM_RECOGNIZE_NEXT_WORD_REPLY
SmNrecognizedPhraseCallback |  | X | SM_RECOGNIZED_PHRASE
SmNrecognizedTextCallback |  | X | SM_RECOGNIZE_TEXT
SmNrecognizedWordCallback |  | X | SM_RECOGNIZE_WORD
SmNreleaseFocusCallback | X |  | SM_RELEASE_FOCUS
SmNremoveFromVocabCallback | X |  | SM_REMOVE_FROM_VOCAB_REPLY
SmNremovePronunciationCallback | X |  | SM_REMOVE_PRONUNCIATION_REPLY
SmNreportEngineErrorCallback |  | X | SM_REPORT_ENGINE_ERROR
SmNrequestFocusCallback | X |  | SM_REQUEST_FOCUS
SmNrequestMicOffCallback | X |  | SM_REQUEST_MIC_OFF_REPLY
SmNrequestMicOnCallback | X |  | SM_REQUEST_MIC_ON_REPLY
SmNrestoreSpeechDataCallback | X |  | SM_RESTORE_SPEECH_DATA_REPLY
SmNsaveSpeechDataCallback | X |  | SM_SAVE_SPEECH_DATA_REPLY
SmNsetCallback | X |  | SM_SET_REPLY
SmNsetDefaultCallback | X |  | SM_SET_DEFAULT_REPLY
SmNsetUserInfoCallback | X |  | SM_SET_USER_INFO_REPLY
SmNundefineVocabCallback | X |  | SM_UNDEFINE_VOCAB_REPLY
SmNutteranceCompletedCallback |  | X | SM_UTTERANCE_COMPLETED
SmNwordCorrectionCallback | X |  | SM_WORD_CORRECTION_REPLY

## Reply Structure Functions for Unsolicited Callbacks

The following is a list of all unsolicited callbacks available for processing messages from the speech engine. Each callback is followed by a list of the reply structure functions that can be called from within it.

- SmNaudioLevelCallback
  - SmGetRc
  - SmGetAudioLevel

- SmNcommandWordCallback
  - SmGetRc
  - SmGetApplication
  - SmGetFirmWords

- SmNdetachRequestedCallback
  - SmGetRc

- SmNengineStateCallback
  - SmGetRc
  - SmGetengineState

- SmNeventSynchCallback
  - SmGetRc
  - SmGetEventId
  - SmGetEventOptions

- SmNfocusGrantedCallback
  - SmGetRc

- SmNfocusLostCallback
  - SmGetRc

- SmNfocusStateCallback
  - SmGetRc
  - SmGetFocusState
  - SmGetApplication

- SmNmicOffRequestedCallback
  - SmGetRc

- SmNmicOnRequestedCallback
  - SmGetRc

- SmNmicStateCallback
  - SmGetRc
  - SmGetMicState

- SmNplayMessageStatusCallback
  - SmGetRc
  - SmGetMsgName
  - SmGetStatus

- SmNplayUtteranceStatusCallback
  - SmGetRc
  - SmGetStatus
  - SmGetUtteranceNumber

- SmNplayWordsStatusCallback
  - SmGetRc
  - SmGetStatus
  - SmGetTags

- SmNrecognizedPhraseCallback
  - SmGetRc
  - SmGetFirmWords
  - SmGetVocabName
  - SmGetPhraseState

- SmNrecognizedTextCallback
  - SmGetRc
  - SmGetFirmWords
  - SmGetInfirmWords
  - SmGetTimes

- SmNrecognizedWordCallback
  - SmGetRc
  - SmGetAlternates
  - SmGetFirmWords
  - SmGetTimes

- SmNreportEngineErrorCallback
  - SmGetRc
  - SmGetMicState
  - SmGetSeverity

- SmNutteranceCompletedCallback
  - SmGetRc
  - SmGetUtteranceNumber

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]