|
|
SMAPI (Speech Manager Application
Programming Interface) Reference
IBM ViaVoice. SDK for Windowsa
Printed in the USA
Note
Before using this information and the product it supports, be sure to read the general information under Appendix
D "Notices".
First Edition (August 1998)
The following paragraph does not apply to the United Kingdom or any country where such provisions are
inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied
warranties in certain transactions, therefore, this statement may not apply to you.
This publication could include technical inaccuracies or typographical errors. Changes are periodically made to
the information herein; these changes will be incorporated in new editions of the publication. IBM may make
improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.
It is possible that this publication may contain reference to, or information about, IBM products (machines and
programs), programming, or services that are not announced in your country. Such references or information
must not be construed to mean that IBM intends to announce such IBM products, programming, or services in
your country.
Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing
representative.
Contents
About this Book 19
Who Should Read This Book ..... . . . . ..... . . . ..... . . . . .... 19
RelatedPublications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Part 1: IBM Speech API (SMAPI)
Chapter 1 SMAPI Overview 21
Formatof theFunctionCallDescriptions . . . . . . . . . . . . . . . . . . . . . 21
NamingConventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
SMAPI Function Calls by Group ... . . . . ..... . . . ..... . . . . .... 24
Attribute HandlingFunctions.... . . . . ..... . . . ..... . . . . .... 24
Callback and Dispatching Functions . . ..... . . . ..... . . . . .... 24
Data Access Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
ConnectionFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
SessionFunctions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Database Functions.. . . . . ..... . . . . ..... . . . ..... . . . . .... 28
Speech Recognition Engine State Functions . . . . . . . . . . . . . . . . 29
Vocabulary Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Audio Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Parallel SessionAPI Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Chapter 2 Starter Set APIs 33
StarterSet SMAPIs for Command and Control . . . ..... . . . . .... 33
Establishing a Recognition Session. . . ..... . . . ..... . . . . .... 34
Setting Up and Enabling Vocabularies ..... . . . ..... . . . . .... 34
Directing the Engine toProcess Speech. . . ..... . . . ...... . . . 35
IBM SMAPI Reference
Contents
ProcessingRecognized Commands. . . . . ..... . . . ..... . . . . . 35
Disconnecting fromthe Engine ..... . . . . ..... . . . ..... . . . . . 36
Starter Set SMAPIs for Dictation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Establishing a Recognition Session.. . . . . ..... . . . ..... . . . . . 37
Setting Up and Enabling Vocabularies. . . . ..... . . . ..... . . . . . 37
Directing the Engine to ProcessSpeech . . ..... . . . ..... . . . . . 38
ProcessingRecognized Text . . ..... . . . . ..... . . . ..... . . . . . 38
Correcting Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Disconnecting fromthe Engine ..... . . . . ..... . . . ..... . . . . . 40
Chapter 3 Function Calls to the Speech Recognition Engine 41
SmAddCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
SmAddPronunciation . ..... . . . . ..... . . . . ..... . . . ..... . . . . . 42
SmAddToVocab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
SmApiVersionCheck. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
SmAutoComplete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
SmCancelPlayback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
SmClose. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
SmConnect. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
SmCorrectText. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
SmDefineGrammar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
SmDefineVocab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
SmDefineVocabEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
SmDetachSessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
SmDisableVocab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
SmDiscardData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
SmDiscardSpeechData .... . . . . ..... . . . . ..... . . . ..... . . . . . 74
SmDisconnect .. . . . . ..... . . . . ..... . . . . ..... . . . ..... . . . . . 76
SmDispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
SmEnableVocab. . . . . ..... . . . . ..... . . . . ..... . . . ..... . . . . . 79
SmEventNotify. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
SmHaltRecognizer . . . ..... . . . . ..... . . . . ..... . . . ..... . . . . . 83
SmMicOff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
SmMicOn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
IBM ViaVoice SDK for Windows
Contents
SmNewContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
SmOpen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
SmPlayMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
SmPlayUtterance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
SmPlayWords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
SmQuery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
SmQueryAddedWords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
SmQueryAddedWordsEx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
SmQueryAlternates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
SmQueryBinary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
SmQueryDefault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
SmQueryEnabledVocabs. . . . ..... . . . . ..... . . . ..... . . . . ... 119
SmQueryEnrollIds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
SmQueryLanguages... . . . . ..... . . . . ..... . . . ..... . . . . ... 123
SmQueryPhraseAlternatives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
SmQueryPronunciation. . . . . ..... . . . . ..... . . . ..... . . . . ... 127
SmQueryPronunciations . . . . ..... . . . . ..... . . . ..... . . . . ... 129
SmQueryPronunciationsEx . . ..... . . . . ..... . . . ..... . . . . ... 131
SmQueryScripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
SmQuerySessions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
SmQuerySpeechData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
SmQueryTasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
SmQueryTopics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
SmQueryUserDefault. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
SmQueryUserInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
SmQueryUsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
SmQueryVocabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
SmQueryWord. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
SmReceiveMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
SmRecognizeNextWord. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
SmReleaseFocus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
SmRemoveCallback.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
SmRemoveFromVocab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
IBM SMAPI Reference
Contents
SmRemovePronunciation... . . . . ..... . . . . ..... . . . ..... . . . . 159
SmRequestFocus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
SmRequestMicOff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163
SmRequestMicOn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164
SmRestoreSpeechData.... . . . . ..... . . . . ..... . . . ..... . . . . 165
SmSaveSpeechData . ..... . . . . ..... . . . . ..... . . . ..... . . . .167
SmSet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
SmSetArg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
SmSetBinary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179
SmSetDefault.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
SmSetDirectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
SmSetUserDefault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
SmSetUserInfo.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
SmUndefineVocab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
SmWordCorrection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Chapter 4 Data Access Functions 195
SmGetAlphabets . . . . ..... . . . . ..... . . . . ..... . . . ..... . . . .195
SmGetAlternates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
SmGetAnnotations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
SmGetApplication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
SmGetApplications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
SmGetAudioLevel. . . . ..... . . . . ..... . . . . ..... . . . ..... . . . . 202
SmGetBinaryItemValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
SmGetCodePage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
SmGetDescriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205
SmGetEngineState. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
SmGetEnrollId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
SmGetEnrollIds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .210
SmGetEventId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212
SmGetEventOptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
SmGetFirmWords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
SmGetFlags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
IBM ViaVoice SDK for Windows
Contents
SmGetFocusChangeReason. ..... . . . . ..... . . . ..... . . . . ... 217
SmGetFocusState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
SmGetGrammarPath.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
SmGetIncrements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
SmGetItemValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
SmGetLanguages ..... . . . . ..... . . . . ..... . . . ..... . . . . ... 222
SmGetMicState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
SmGetMsgName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
SmGetMsgType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
SmGetNameValue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
SmGetNumberWordMsgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
SmGetOptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
SmGetPercentages.... . . . . ..... . . . . ..... . . . ..... . . . . ... 229
SmGetPhraseScore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
SmGetPhraseState. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
SmGetPreferred. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
SmGetPronunciations.. . . . . ..... . . . . ..... . . . ..... . . . . ... 234
SmGetRc.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
SmGetRcDescription. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
SmGetRcName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
SmGetSampleRates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
SmGetScriptFlags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
SmGetScripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
SmGetService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
SmGetSessionId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
SmGetSeverity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
SmGetSizes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
SmGetSpeechDataArchive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
SmGetSpeechDataOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
SmGetSpeechDataSize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
SmGetSpeechDataVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
SmGetSpelling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
SmGetSpellings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
IBM SMAPI Reference
Contents
SmGetStates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
SmGetStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
SmGetTags.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
SmGetTask.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
SmGetTaskFlags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258
SmGetTasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
SmGetTimes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260
SmGetTopics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .262
SmGetTrained. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
SmGetUserId. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
SmGetUserIds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
SmGetUsers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
SmGetUtteranceNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
SmGetVocabList. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
SmGetVocabName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
SmGetVocabPath. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
SmGetVocWords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .274
SmGetWords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
SmGetWordTimes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .277
SmReturnRc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
SmReturnRcDescription. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
SmReturnRCName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .281
Chapter 5 Reply Message Structures and Callbacks 283
Reply Message Structures Received from the Speech Engine . . . . 283
Callbacks . ..... . . . . ..... . . . . ..... . . . . ..... . . . ..... . . . . 294
Reply Structure Functions for Unsolicited Callbacks . . . . . . . . . . . . 297
Chapter 6 Data Types 301
caddr_t . . ..... . . . . ..... . . . . ..... . . . . ..... . . . ..... . . . . 301
SmArg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
SmArgVal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
IBM ViaVoice SDK for Windows
Contents
SmHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
SM_ANNOTATION.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Sm_Msg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
SM_VOCWORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
SM_WORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Chapter 7 SMAPI Attributes 307
System Dependent Definition for Argument Lists . . . . . . . . . . . . . . 307
Argument Attribute List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
ApplicationInformation Attributes . . . . . . . . . . . . . . . . . . . . . . . . 307
SmNapplicationName. . . ..... . . . . ..... . . . ..... . . . . ... 307
Requested Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
SmNresetServices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
SmNdatabase.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
SmNrecognize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
OptionsFlags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
SmNdiscardSessionData.. . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
SmNdiscardSessionAdaptation . . . . ..... . . . ..... . . . . ... 308
SmNSaveSessionData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
SmNSaveSessionAdaptation.. . . . . ..... . . . ..... . . . . ... 308
WindowHandle ..... . . . . ..... . . . . ..... . . . ..... . . . . ... 309
SmNwindowHandle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
User DefinitionArguments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
SmNaudioHost.... . . . . ..... . . . . ..... . . . ..... . . . . ... 309
SmNconnectID.... . . . . ..... . . . . ..... . . . ..... . . . . ... 309
SmNenrollID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
SmNnavigator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
SmNtask. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
SmNuserID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Part 2: IBM Dictation Macro API (DMAPI)
Chapter 8 DMAPI Overview
311
Formatof theFunctionCallDescriptions . . . . . . . . . . . . . . . . . . . . 311
IBM SMAPI Reference
Contents
DMAPI Function Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312
Chapter 9 DMAPI Function Calls
315
DmClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .315
DmFlushEx.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
DmFreeMacro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
DmFreeMacroEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .318
DmFreeNames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
DmGetGroupsOnPage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
DmGetKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321
DmGetKeyGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .322
DmGetKeyGroupOption.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
DmGetKeyGroupOptionSelection. . . . . . . . . . . . . . . . . . . . . . . . . . . 324
DmGetLastError. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
DmGetMacro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .327
DmGetMacroEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
DmGetNumberOfGroups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
DmGetNumberOfOptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
DmGetNumberOfSelections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
DmGetTemplate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
DmIsNumberFlagged. ..... . . . . ..... . . . . ..... . . . ..... . . . . 336
DmKeywordFromType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .337
DmOpen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
DmQueryDelimiters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
DmQueryMacroNames.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
DmQueryTemplateNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
DmQuerySetAndStoreKey. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
DmSetKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .345
DmStartMacroEditor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
DmStoreKey. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
DmTypeFromKeyword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .348
DmUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .350
IBM ViaVoice SDK for Windows
Contents
Chapter 10 Data Types
351
DMERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
DM_MACRO_STRUCT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
DM_TEMPLATE_FIELD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Part 3: IBM SMAPI Grammar Compiler API
Chapter 11 SMAPI Grammar Compiler API Overview 355
Formatof theFunctionCallDescriptions . . . . . . . . . . . . . . . . . . . . 355
Grammar Compiler API Function Calls . . . . . . . . . . . . . . . . . . . . . . 356
Chapter 12 SMAPI Grammar Compiler API Function Calls 357
VtAddArg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
VtCompileGrammar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
VtGetMessage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
VtGetTranslation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
VtLoadFSG . . . . . ..... . . . . ..... . . . . ..... . . . ..... . . . . ... 362
VtSethArg.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
VtUnloadFSG. . . . ..... . . . . ..... . . . . ..... . . . ..... . . . . ... 364
Chapter 13 Data Types 365
VtArg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Part 4: Other ViaVoice APIs
Chapter 14 VtGeneratePronunciations
369
VtGeneratePronunciations . . ..... . . . . ..... . . . ..... . . . . ... 369
IBM SMAPI Reference
Part 5: Appendixes
Appendix A
Contents
SMAPI Return Codes, Messages, Message Types 371
SMAPI Return Codes and Messages .. . . . . ..... . . . ..... . . . . 371
Engine Return Codes and Messages... . . . . ..... . . . ..... . . . . 375
Status Codesand Messages. . . . ..... . . . . ..... . . . ..... . . . . 376
SMAPI MessageTypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .377
SMAPI MessageExplanations. . . ..... . . . . ..... . . . ..... . . . . 381
SM_RC_ACOUSTICS_TOO_LONG. . . . . ..... . . . ..... . . . . 381
SM_RC_ADDED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .381
SM_RC_ADDWORD_LIMIT_EXCEEDED. . . . . . . . . . . . . . . . . . 382
SM_RC_ALREADY_CONNECTED . . . . . . . . . . . . . . . . . . . . . . . 382
SM_RC_ALREADY_OPENED. . . . . . . . . . . . . . . . . . . . . . . . . . . 382
SM_RC_ASSOC_EVENT_SEM_FAILED . . . . . . . . . . . . . . . . . .383
SM_RC_AUDIO_FORCED_MIC_OFF . . . . . . . . . . . . . . . . . . . .383
SM_RC_AUDIO_IN_USE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .383
SM_RC_AUDIO_OVERRUN . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
SM_RC_BAD_ACOUSTICS . . . . . . . . . . . . . . . . . . . . . . . . . . . .384
SM_RC_BAD_ADDWORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . .384
SM_RC_BAD_AP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385
SM_RC_BAD_AUDIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
SM_RC_BAD_DECO. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
SM_RC_BAD_DESCRIPTION. . . . . . . . . . . . . . . . . . . . . . . . . . . 386
SM_RC_BAD_ENROLLID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
SM_RC_BAD_ITEM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
SM_RC_BAD_LANGUAGE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
SM_RC_BAD_MESSAGE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
SM_RC_BAD_MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .387
SM_RC_BAD_NAME. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
SM_RC_BAD_SCRIPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
SM_RC_BAD_TAG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .388
SM_RC_BAD_TASKID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
SM_RC_BAD_USERID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
SM_RC_BAD_UTTNO.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
SM_RC_BAD_VALUE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
SM_RC_BAD_VOCAB.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
IBM ViaVoice SDK for Windows
Contents
SM_RC_BUSY_LAST_UTTERANCE. . . . . . . . . . . . . . . . . . . . . 390
SM_RC_BUSY_WORD_CORRECTION. . . . . . . . . . . . . . . . . . . 391
SM_RC_CALLBACK_LIST_CHANGED. . . . . . . . . . . . . . . . . . . 391
SM_RC_CONNECTION_CHANGED . . . . . . . . . . . . . . . . . . . . . 391
SM_RC_CREATE_EVENT_SEM_FAILED . . . . . . . . . . . . . . . . . 392
SM_RC_CREATE_MBOX_FAILED. . . . . . . . . . . . . . . . . . . . . . . 392
SM_RC_DEEALLOCATING_SH_MEM.. . . . . . . . . . . . . . . . . . . 392
SM_RC_EALLBUSY. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
SM_RC_EALLOC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
SM_RC_EAPIVERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
SM_RC_EBADAPPNAME. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
SM_RC_EBADHANDLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
SM_RC_EINVAL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
SM_RC_ENOCONN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
SM_RC_ENOHANDLES. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
SM_RC_ENOMEM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
SM_RC_ENOMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
SM_RC_ENOSERVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
SM_RC_ENROLLID_BUSY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
SM_RC_ENROLLID_EXISTS. . . . . . . . . . . . . . . . . . . . . . . . . . . 397
SM_RC_ENROLLID_RUNNING. . . . . . . . . . . . . . . . . . . . . . . . . 397
SM_RC_ENROLLMENT_NOT_COMPLETE . . . . . . . . . . . . . . . 397
SM_RC_FREE_MEM_ERROR.. . . . . . . . . . . . . . . . . . . . . . . . . 398
SM_RC_EXISTS_IN_NOTIFY. . . . . . . . . . . . . . . . . . . . . . . . . . . 398
SM_RC_FOCUS_DENIED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
SM_RC_FOCUS_GRANTED. . . . . . . . . . . . . . . . . . . . . . . . . . . 399
SM_RC_INCOMPATIBLE_ENROLLMENT . . . . . . . . . . . . . . . . . 399
SM_RC_ILLEGAL_SPOKENLIKE. . . . . . . . . . . . . . . . . . . . . . . . 399
SM_RC_ILLEGAL_SPELLING. . . . . . . . . . . . . . . . . . . . . . . . . . 400
SM_RC_INVALID_PARM_MAX_LEN . . . . . . . . . . . . . . . . . . . . . 400
SM_RC_INVOCAB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
SM_RC_MIC_ALREADY_OFF. . . . . . . . . . . . . . . . . . . . . . . . . . 401
SM_RC_MIC_ALREADY_ON . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
SM_RC_MIC_OFF_PENDING. . . . . . . . . . . . . . . . . . . . . . . . . . 401
SM_RC_MIC_ON_PENDING. . . . . . . . . . . . . . . . . . . . . . . . . . . 402
SM_RC_MISMATCHED_ACOUSTICS. . . . . . . . . . . . . . . . . . . . 402
SM_RC_MISMATCHED_ALPHABET . . . . . . . . . . . . . . . . . . . . . 402
SM_RC_MISMATCHED_LANGUAGE. . . . . . . . . . . . . . . . . . . . . 403
IBM SMAPI Reference
Contents
SM_RC_MISMATCHED_SCRIPT. . . . . . . . . . . . . . . . . . . . . . . . 403
SM_RC_MISSING_EXTERN. . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
SM_RC_MULTIPLE_SPELLINGS.. . . . . . . . . . . . . . . . . . . . . . . 404
SM_RC_NAV_ALREADY_DEFINED. . . . . . . . . . . . . . . . . . . . . . 404
SM_RC_NO_FOCUS_APP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
SM_RC_NO_MORE_CONNECTIONS . . . . . . . . . . . . . . . . . . . . 405
SM_RC_NO_SPACE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
SM_RC_NO_SPACE_INIT_ENROLL . . . . . . . . . . . . . . . . . . . . .405
SM_RC_NO_SPACE_INIT_RECO . . . . . . . . . . . . . . . . . . . . . . .406
SM_RC_NO_SPACE_MIC_ON . . . . . . . . . . . . . . . . . . . . . . . . . . 406
SM_RC_NO_SPACE_TERM_ENROLL. . . . . . . . . . . . . . . . . . . . 406
SM_RC_NOT_ADDED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .407
SM_RC_NOT_DELETED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .407
SM_RC_NOT_IN_NOTIFY . . . . . . . . . . . . . . . . . . . . . . . . . . . . .407
SM_RC_NOT_INVOCAB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
SM_RC_NOT_VALID_REQUEST. . . . . . . . . . . . . . . . . . . . . . . . 408
SM_RC_NOT_WHILE_MIC_ON. . . . . . . . . . . . . . . . . . . . . . . . . 408
SM_RC_NOT_WHILE_PLAYING. . . . . . . . . . . . . . . . . . . . . . . . . 409
SM_RC_NOT_YET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .409
SM_RC_OK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
SM_RC_OPEN_SYNCH_QUEUE_FAILED. . . . . . . . . . . . . . . . . 410
SM_RC_PLAY_OPEN_ERROR. . . . . . . . . . . . . . . . . . . . . . . . . . 410
SM_RC_QUEUE_CLOSE_ERROR. . . . . . . . . . . . . . . . . . . . . . . 410
SM_RC_RECORD_OPEN_ERROR. . . . . . . . . . . . . . . . . . . . . . 411
SM_RC_REPLY_NULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .411
SM_RC_SERVER_ERROR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
SM_RC_SERVER_FILE_CLOSE_ERROR . . . . . . . . . . . . . . . . . 412
SM_RC_SERVER_FILE_OPEN_ERROR. . . . . . . . . . . . . . . . . . 412
SM_RC_SERVER_FILE_READ_ERROR. . . . . . . . . . . . . . . . . . 413
SM_RC_SERVER_FILE_WRITE_ERROR . . . . . . . . . . . . . . . . . 413
SM_RC_SERVER_MALLOC_ERROR . . . . . . . . . . . . . . . . . . . .414
SM_RC_SERVER_PROCESS_ERROR . . . . . . . . . . . . . . . . . . . 414
SM_RC_SERVER_TERMINATED.. . . . . . . . . . . . . . . . . . . . . . . 415
SM_RC_SM_EINVAL_MSG_TYPE. . . . . . . . . . . . . . . . . . . . . . . 415
SM_RC_SM_NOT_ACTIVE_CLIENT . . . . . . . . .. . . . . . . .. . . . 415
SM_RC_SM_NOT_OPEN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
SM_RC_SUB_UNSET_ERROR . . . . . . . . . . . . . . . . . . . . . . . . .416
SM_RC_SPELLING_TOO_LONG. . . . . . . . . . . . . . . . . . . . . . . . 416
IBM ViaVoice SDK for Windows
Contents
SM_RC_USERID_BUSY. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
SM_RC_USERID_EXISTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
SM_RC_WRONG_SM_VERSION . . . . . . . . . . . . . . . . . . . . . . . 417
SM_STAT_BAD_AUDIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
SM_STAT_BAD_MESSAGE . . . ...... . . . ..... . . . ...... . . 418
SM_STAT_BAD_TAG. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
SM_STAT_BAD_UTTERANCE. . . . . . . . . . . . . . . . . . . . . . . . . . 419
SM_STAT_ENROLLMENT_BUSY. . . . . . . . . . . . . . . . . . . . . . . . 419
SM_STAT_ENROLLMENT_COMPLETE. . . . . . . . . . . . . . . . . . . 419
SM_STAT_ENROLLMENT_FAILED . . . . . . . . . . . . . . . . . . . . . . 420
SM_STAT_ENROLLMENT_RECORDING. . . . . . . . . . . . . . . . . . 420
SM_STAT_ENROLLMENT_RUNNING . . . . . . . . . . . . . . . . . . . . 420
SM_STAT_PLAY_START. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
SM_STAT_PLAY_STOP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
ROUTER.MSGLog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
SM_INIT_DATABASE_REPLY.. . . . . . . . . . . . . . . . . . . . . . . . . . 423
SM_INIT_RECOGNIZER_REPLY. . . . . . . . . . . . . . . . . . . . . . . . 423
SM_TERMINATE_DATABASE_REPLY . . . . . . . . . . . . . . . . . . . . 423
SM_TERMINATE_RECOGNIZER_REPLY . . . . . . . . . . . . . . . . . 423
Appendix B DMAPI Return Codes and Messages 425
DMAPI Return Codesand Messages. . . ..... . . . ..... . . . . ... 425
DMAPIMessage Explanations . . . ...... . . . ..... . . . ...... . . 427
DM_ERR_ACT_FILE_PARSE.. . . . . . . . . . . . . . . . . . . . . . . . . . 427
DM_ERR_BAD_EXE_FORMAT . . . . . . . . . . . . . . . . . . . . . . . . . 427
DM_ERR_DUPLICATE_MACRO. . . . . . . . . . . . . . . . . . . . . . . . . 427
DM_ERR_EACCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
DM_ERR_EBADF.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
DM_ERR_EMFILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
DM_ERR_ENOENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
DM_ERR_ENOSPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
DM_ERR_EXPDLL_ERR . ..... . . . . ..... . . . ..... . . . . ... 429
DM_ERR_EXPDLL_LOAD_FAILED . . ..... . . . ..... . . . . ... 430
DM_ERR_EXPDLL_QUERYFUN_FAILED . . . . . . . . . . . . . . . . . 430
DM_ERR_EXPDLL_TIMEOUT.. . . . . ..... . . . ..... . . . . ... 430
DM_ERR_FILE_READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
DM_ERR_INI_FILE_PARSE. . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
IBM SMAPI Reference
Appendix C
Appendix D
Index
Contents
DM_ERR_INVALID_DOMAIN . . . . . . . . . . . . . . . . . . . . . . . . . . .431
DM_ERR_INVALID_HANDLE . . . . . . . . . . . . . . . . . . . . . . . . . . .432
DM_ERR_INVALID_KEYTYPE . . . . . . . . . . . . . . . . . . . . . . . . . .432
DM_ERR_INVALID_KEYWORD. . . . . . . . . . . . . . . . . . . . . . . . . 432
DM_ERR_INVALID_LANGUAGE. . . . . . . . . . . . . . . . . . . . . . . . . 433
DM_ERR_INVALID_MACRO. . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
DM_ERR_INVALID_MACROFILE. . . . . . . . . . . . . . . . . . . . . . . . 433
DM_ERR_INVALID_MACRORELEASE . . . . . . . . . . . . . . . . . . .434
DM_ERR_INVALID_MACROVERSION. . . . . . . . . . . . . . . . . . . . 434
DM_ERR_INVALID_TEMPLATE. . . . . . . . . . . . . . . . . . . . . . . . . 434
DM_ERR_INVALID_USERID. . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
DM_ERR_LOAD_RESOURCE_DLL. . . . . . . . . . . . . . . . . . . . . . 435
DM_ERR_MACRO_NESTING. . . . . . . . . . . . . . . . . . . . . . . . . . . 435
DM_ERR_MACRO_NOT_FOUND. . . . . . . . . . . . . . . . . . . . . . . . 436
DM_ERR_MALLOC.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
DM_ERR_MISSING_CLIPBRD_FORMAT . . . . . . . . . . . . . . . . . 436
DM_ERR_NOT_ENOUGH_SHARED_MEMORY . . . . . . . . . . . . 437
DM_ERR_NOTIFY_EXCEEDED.. . . . . . . . . . . . . . . . . . . . . . . . 437
DM_ERR_NOUPDATE.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
DM_ERR_OK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
DM_ERR_OPEN_CLIPBOARD_FAILED. . . . . . . . . . . . . . . . . . . 438
DM_ERR_OUT_OF_SYSTEM_RES. . . . . . . . . . . . . . . . . . . . . . 438
DM_ERR_FILE_SET_AFFECT_FLAG . . . . . . . . . . . . . . . . . . . .439
DM_ERR_SHARED_MEM_UNDEFINED . . . . . . . . . . . . . . . . . . 439
DM_ERR_SYSTEM_PARM_LONG. . . . . . . . . . . . . . . . . . . . . . . 439
DM_ERR_TEMPLATE_NOT_FOUND. . . . . . . . . . . . . . . . . . . . . 440
DM_ERR_TRANSFER_TO_CLIPBRD . . . . . . . . . . . . . . . . . . . .440
DM_ERR_UNDEFINED. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
DM_ERR_UNEXPECTED_EOF . . . . . . . . . . . . . . . . . . . . . . . . . 441
Speech Recognition Engine Error Messages 443
Notices 445
Trademarks .. . . . . ..... . . . . ..... . . . . ..... . . . ..... . . . .446
447
IBM ViaVoice SDK for Windows
About This Book
This book provides detailed information on developing Windowsa 95/98 or Windows NT. speech-
aware applications using IBM ViaVoice. Speech Solutions Developer’s Kit (SDK) for Windows and
Speech Manager Application Programming Interfaces (SMAPI) from IBM. The ViaVoice SDK
provides three sets of APIs: Speech Manager APIs (SMAPI), Dictation Macro APIs (DMAPI), and
Grammar Compiler APIs. This document is a PDF format viewable with the Adobe Acrobat Reader
and we recommend that you print it out.
Who Should Read This Book
Read this book if you are a software developer interested in writing Windows 95/98 or Windows NT
4.0 applications using the ViaVoice SDK APIs.
Related Publications
Refer to the following publications included with this version for additional programming, reference,
and design information:
. SMAPI Developer’s Guide
. SAPI Reference
. ActiveX Developer’s Guide
. ActiveX Developer’s Guide Help File
Refer to the following sources for additional programming, reference, and design information:
. ViaVoice Developer’s Corner website at:
http://www.ibm.com/viavoice/dev_home.html
. IBM ViaVoice SDK Web Channel at:
http://www.software.ibm.com/viavoice/subscribe.html
. OLE Automation Reference from Microsoft
IBM SMAPI Reference
IBM ViaVoice SDK for Windows
Chapter 1 SMAPI Overview
This chapter describes the format of the function calls that are presented in Chapter 3 “Function Calls
to the Speech Recognition Engine” and Chapter 4 “Data Access Functions”. Chapter 3 contains the
function calls that go directly to the speech recognition engine. Chapter 4 contains the function calls
that do not interact with the engine; they provide local access to the logical contents of a message that
has already been received.
This chapter also lists the calls by functional group.
Format of the Function Call Descriptions
The description of each function call contains the following information:
Function Name
The name of the function call.
Purpose
The purpose and description of the function call.
Syntax
The syntax of the function as declared in SMAPI.H.
Parameters
Definitions of the parameters.
IBM SMAPI Reference
SMAPI Overview
Return Values
Return values are listed in two groups:
.
Return values that are set by the SMAPI or as a result of an unsuccessful connection to the
speech recognition engine. These values are always returned by the called function whether it
was called synchronously or asynchronously.
.
Return values that are set from within the speech recognition engine. These values are returned
by the called function only if it was called synchronously. If it was called asynchronously, the
speech-aware application must retrieve this type of return value from within the appropriate
callback by using the SmGetRc function.
For detailed descriptions of SMAPI errors, reference “SMAPI Return Codes and Messages” on
page 369.
Reply Structure Functions by Message Type
A list of all reply message structures that can be received from the speech recognition engine; and
for each listed reply message structure, the SmGet functions that can extract data from it.
Task Related Functions and Callbacks
A list of functions and callbacks broadly related by task to this function. This is applicable to
functions that do not return a reply structure. For example, task related groups include:
.
Vocabulary Processing
.
User Processing
.
Application Initiation
.
Speech Processing
.
Application Termination
IBM ViaVoice SDK for Windows
This section also lists related unsolicited callbacks.
Reply Structure-Related Functions and Callbacks
Clarifies when the SmGet functions can be called. If the function prototype SmXxx is listed as
related for any SmGet function, then that function can be called as follows:
.
Immediately after a synchronous SmXxx call
.
From SmNXxxCallback after an asynchronous SmXxx call
.
From the message reply structure after an asynchronous SmXxx call.
Naming Conventions
Use the following conventions when creating various IDs and names passed to the speech recognition
engine:
.
User IDs can consist of only lowercase alphanumeric characters plus the underscore and
hyphen characters.
.
Descriptions cannot contain a new line character.
.
An ID must contain at least one character.
The following values, found in the file SMLIMITS.H, shows the maximum lengths of key variables:
#define SM_MAX_USERID_LEN 8
#define SM_MAX_ENROLLID_LEN 8
#define SM_MAX_TASKNAME_LEN 8
#define SM_MAX_SCRIPTNAME_LEN 8
IBM SMAPI Reference
SMAPI Overview
SMAPI Function Calls by Group
The following information lists the SMAPI calls by functional group.
Attribute Handling Functions
These functions are implemented locally within the application's address space by the SMAPI layer
and do not require any interaction with the speech recognition engine. Consequently, they can be made
at any time, independent of the speech focus.
. SmSetArg
Callback and Dispatching Functions
These functions are also implemented locally in the application's address space by the SMAPI layer.
. SmAddCallback
. SmDispatch
. SmReceiveMsg
. SmRemoveCallback
Data Access Functions
The data access functions manipulate data received by the application. They are independent of the
speech focus.
. SmGetAlphabets
. SmGetAlternates
. SmGetAnnotations
. SmGetApplication
. SmGetApplications
. SmGetAudioLevel
IBM ViaVoice SDK for Windows
. SmGetBinaryItemValue
. SmGetCodepage
. SmGetDefaultTopics
. SmGetDescriptions
. SmGetEngineState
. SmGetEnrollId
. SmGetEnrollIds
. SmGetEventId
. SmGetEventOptions
. SmGetFirmWords
. SmGetFlags
. SmGetFocusState
. SmGetInfirmWords
. SmGetItemValue
. SmGetLanguages
. SmGetMicState
. SmGetMsgName
. SmGetMsgType
. SmGetNameValue
. SmGetNumberWordMsgs
. SmGetOptions
. SmGetPercentages
. SmGetPhraseScore
. SmGetPreferred
. SmGetPronunciations
. SmGetRc
IBM SMAPI Reference
SMAPI Overview
. SmGetRcDescription
. SmGetRcName
. SmGetSampleRates
. SmGetScriptFlags
. SmGetScripts
. SmGetService
. SmGetSessionId
. SmGetSeverity
. SmGetSizes
. SmGetSpeechDataArchive
. SmGetSpeechDataOptions
. SmGetSpeechDataSize
. SmGetSpeechDataVersion
. SmGetSpelling
. SmGetSpellings
. SmGetStates
. SmGetStatus
. SmGetTags
. SmGetTask
. SmGetTaskFlags
. SmGetTasks
. SmGetTimes
. SmGetTopics
. SmGetTrained
. SmGetUserId
. SmGetUserIds
IBM ViaVoice SDK for Windows
. SmGetUsers
. SmGetUtteranceNumber
. SmGetVocabList
. SmGetVocabName
. SmGetVocabPath
. SmGetVocWords
. SmGetWords
. SmGetWordTimes
. SmReturnRc
. SmReturnRcDescription
. SmReturnRcName
Connection Functions
These functions enable an application to connect to, or disconnect from, the speech recognition engine.
. SmApiVersionCheck
. SmOpen
. SmConnect
. SmDisconnect
. SmClose
IBM SMAPI Reference
SMAPI Overview
Session Functions
The session-sharing related calls are appropriate when an application is in a particular state.
. SmDetachSessions
. SmReleaseFocus
. SmRequestFocus
. SmRequestMicOff
. SmRequestMicOn
Database Functions
These functions access database information. Although they do divert some engine resources, they do
not interfere with the application's use of the speech recognition engine. Consequently, they are
permitted at any time after calling SmConnect. Some returned information pertains to a specific
session; some pertains to the speech recognition engine as a whole.
. SmQueryAddedWords
. SmQueryAddedWordsEx
. SmQueryAlternates
. SmQueryDefaults
. SmQueryEnabledVocabs
. SmQueryEnrollIds
. SmQueryLanguages
. SmQueryPronunciation
. SmQueryPronunciations
. SmQueryPronunciationsEx
. SmQuerySessions
. SmQueryTasks
. SmQueryTopics
IBM ViaVoice SDK for Windows
. SmQueryUserDefault
. SmQueryUserInfo
. SmQueryUsers
. SmQueryVocabs
. SmQueryWord
The following functions are administrative. They do not change the state of the engine for the
application with focus:
. SmSetDefault
. SmSetUserDefault
. SmSetUserInfo
Speech Recognition Engine State Functions
These functions set and query the state of the speech recognition engine.
. SmSet
. SmQuery
Vocabulary Functions
These functions change the state of the active, dynamically specified vocabularies, and they are
handled independently for each session. They are transparent to the application.
. SmAddPronunciation
. SmAddToVocab
. SmCorrectText
. SmDefineVocab
. SmDefineVocabEx
. SmDisableVocab
IBM SMAPI Reference
SMAPI Overview
. SmDiscardData
. SmEnableVocab
. SmEventNotify
. SmHaltRecognizer
. SmNewContext
. SmRecognizeNextWord
. SmRemoveFromVocab
. SmRemovePronunciation
. SmUndefineVocab
. SmWordCorrection
Audio Functions
These functions change the state of the audio system. Given a single audio source, this changes the
engine state for the application with focus. Therefore, these functions can only be called by the
application with focus.
. SmCancelPlayback
. SmMicOn
. SmMicOff
. SmPlayMessage
. SmPlayUtterance
. SmPlayWords
IBM ViaVoice SDK for Windows
Parallel Session API Calls
Parallel Session API Calls
The feature of having multiple engine connections from a single application is known as parallel
sessions. If you want more than one connection from your application, you must use the parallel
session calls. The name of a parallel session call is the same as the regular function call except for two
things: the name of the call has the characters Ses inserted after the Sm, for example the parallel
session disconnect call is SmSesDisconnect. Secondly, each parallel session call takes one additional
parameter, which is the session ID. This is always the first parameter. So for the disconnect example,
the call is SmSesDisconnect(hSession), where hSession is the session ID. The session ID is returned
in the first parameter of the SmSesOpen call.
IBM SMAPI Reference
SMAPI Overview
IBM ViaVoice SDK for Windows
Chapter 2 Starter Set APIs
To develop a full-function speech application, you do not need to use all of the functions provided in
the SMAPI. You can use a subset of calls, known as the Starter Set SMAPIs. These calls do not use
separate header or library files.
Note:
The ViaVoice Run Time Kit contains several user interface applications that you must include with
your speech-aware application. Inclusion of these applications ensures optimal recognition performance
for your users. They also serve as reusable applications, so that you don't have to develop
these same functions yourself (setting up the microphone, changing ViaVoice system parameters,
enrollment, and managing the user's personal vocabulary).
Starter Set SMAPIs for Command and Control
When writing your command and control application, you must first establish a connection with the
speech recognition engine. Next, you direct the engine to start processing speech. Your application
interacts with the engine to set up and activate vocabularies and grammars. Most of your work is
involved in processing the recognized speech. When you are done, you disconnect from the engine.
Here are the Starter Set SMAPIs for command and control applications:
. SmOpen
. SmConnect
. SmDefineGrammar
. SmDefineVocab
. SmDefineVocabEx
. SmEnableVocab
. SmDisableVocab
. SmRequestFocus
. SmReleaseFocus
IBM SMAPI Reference
Starter Set APIs
. SmMicOn
. SmMicOff
. SmRecognizeNextWord
. SmReceiveMsg
. SmGetFirmWords
. SmGetAnnotations
. SmDisconnect
. SmClose
Establishing a Recognition Session
To establish a recognition session with the engine, use SmOpen to set up local parameters for starting
the engine and SmConnect, which actually establishes the link between your application and the
engine. You can use SmSetArg to set the input parameters to SmOpen and SmConnect (such as
language, user ID, and enroll ID), but you'll probably want to take the defaults using
SM_DEFAULT_* parameters.
Setting Up and Enabling Vocabularies
A vocabulary is a list of words and/or phrases that the engine uses to match speech input and translate
it into text. Your command and control application specifies the set of active words by defining and
enabling one or more vocabularies. A vocabulary can be predefined in a grammar file, or it can be
created at runtime as a dynamic command vocabulary.
By passing the name of your compiled grammar file to SmDefineGrammar, the words and phrases of
your grammar are defined to the engine. SmDefineVocab allows you to build command vocabularies
dynamically by passing a list of words and phrases that make up that vocabulary. You would also use
this call to define the names for any external references in your grammar file. SmEnableVocab
enables a vocabulary. When decoding speech, the engine searches all of the enabled vocabularies to
translate speech to text. You can have more than one vocabulary active in your application at a time.
IBM ViaVoice SDK for Windows
To improve performance (both recognition speed and accuracy), your application should narrow the
possibilities by enabling and disabling vocabularies as they are needed. You disable a vocabulary by
using the SmDisableVocab call.
Directing the Engine to Process Speech
The speech recognition engine supports both shared and parallel sessions, which means that there can
be several applications connected to the speech recognition engine at the same time, and that a single
application can have more than one connection to the speech recognition engine at the same time, too.
You should design your application so that it cooperates with other speech-aware applications for
control of the microphone. This is known as "having speech focus." An application must have speech
focus to receive recognized text; this may or may not equate to input focus. You need to ensure that
your application has speech focus when it needs it. This is done by using SmRequestFocus to request
speech focus and SmReleaseFocus to release speech focus when you're done.
Once you have speech focus, your application must tell the engine to start processing audio data.
SmMicOn engages the engine to start processing audio data, and SmMicOff tells the engine to stop
processing audio data.
Processing Recognized Commands
The bulk of the work in your application involves getting the recognized commands from the engine
and determining what to do with it. For a command and control application, the engine waits for your
application to direct it to start recognizing words. Use SmRecognizeNextWord to start the engine
looking for words to decode. When the engine recognizes a word from a dynamic command
vocabulary, it returns the word with alternates in the SM_RECOGNIZED_WORD message. When a
phrase is recognized from a grammar, the engine returns the set of words and annotations in the
SM_RECOGNIZED_PHRASE message. Use SmReceiveMsg to accept and process these messages.
In either case, the engine stops decoding until your application makes another
SmRecognizeNextWord call. This gives you a chance to change active vocabularies for recognizing
the next command. While halted, however, the engine continues to capture and process audio, so no
words are lost.
IBM SMAPI Reference
Starter Set APIs
Disconnecting from the Engine
When your application is closing down, you must disconnect and close the session with the speech
recognition engine. To do this, use SmDisconnect and SmClose.
Starter Set SMAPIs for Dictation
The Dictation Starter Set SMAPIs will enable you to develop a dictation application that supports
commands, dictation, word-error playback and correction, and language model cache updates.
. SmOpen
. SmConnect
. SmDefineGrammar
. SmDefineVocab
. SmEnableVocab
. SmDisableVocab
. SmUndefineVocab
. SmMicOn
. SmMicOff
. SmRequestFocus
. SmReleaseFocus
. SmNewContext
. SmRecognizeNextWord
. SmGetFirmWords
. SmGetInfirmWords
. SmHaltRecognizer
. SmEventNotify
IBM ViaVoice SDK for Windows
. SmReceiveMsg
. SmQueryAlternates
. SmPlayWords
. SmWordCorrection
. SmDiscardData
. SmDisconnect
. SmClose
Establishing a Recognition Session
To establish a recognition session with the engine, use SmOpen to set up local parameters for starting
the engine and SmConnect, which actually establishes the link between your application and the
engine. You can use SmSetArg to set the input parameters to SmOpen and SmConnect (such as
language, user ID, and enroll ID), but you'll probably want to take the defaults using
SM_DEFAULT_* parameters.
Setting Up and Enabling Vocabularies
A vocabulary is a list of words and/or phrases that the engine uses to match speech input and translate
it into text. Your application specifies the set of active words by defining and enabling one or more
vocabularies.
A dictation application must first enable a predefined domain (such as the general office vocabulary)
before the engine can use it to decode text. It does so by using the SmEnableVocab function. To have
command words recognized during dictation (such as "stop dictation"), the application must enable the
dictation vocabulary first, and then define the command vocabulary. Grammar vocabularies cannot be
active at the same time as dictation vocabularies, although you can support both dictation and
command and control within the same application. SmDefineGrammar defines a grammar
vocabulary to the engine, and SmDefineVocab defines a dynamic command vocabulary.
SmEnableVocab enables all types of vocabularies (dictation, grammar, and dynamic command).
IBM SMAPI Reference
Starter Set APIs
To improve performance (both recognition speech and accuracy), your application should narrow the
possibilities by enabling and disabling vocabularies as they are needed. You disable a vocabulary by
using the SmDisableVocab call. You can also use SmUndefineVocab to delete a dynamic command
vocabulary, but it must have been disabled first.
Directing the Engine to Process Speech
The speech recognition engine supports both shared and parallel sessions, which means that there can
be several applications connected to the speech recognition engine at the same time, and that a single
application can have more than one connection to the speech recognition engine at the same time, too.
You should design your application so that it cooperates with other speech-aware applications for
control of the microphone. This is known as "having speech focus." An application must have speech
focus to receive recognized text; this may or may not equate to input focus. You need to ensure that
your application has speech focus when it needs it. This is done by using SmRequestFocus to request
speech focus and SmReleaseFocus to release speech focus when you're done.
Once you have speech focus, your application must tell the engine to start processing audio data.
SmMicOn engages the engine to start processing audio data, and SmMicOff tells the engine to stop
processing audio data.
Processing Recognized Text
The bulk of the work in your application involves getting the recognized text from the engine and
determining what to do with it. For a dictation application, the engine waits for your application to
direct it to start recognizing words. Use SmRecognizeNextWord to start the engine looking for words
to decode. If the engine recognizes a word from a dictation vocabulary, the available decoded words
are sent to the application in an SM_RECOGNIZED_TEXT reply message. The
SM_RECOGNIZED_TEXT reply message provides a list of firm and infirm words. Use
SmReceiveMsg to receive messages from the engine. The engine continues decoding words as they
are spoken. SmEventNotify requests that your application be notified when the engine completes
decoding all of the audio up to the point of the call.
Commands are handled as described in the preceding section, "Processing Recognized Commands".
IBM ViaVoice SDK for Windows
When a word is recognized, there is a reply structure generated which you can access via function
calls. This allows you to access both firm and infirm words. When your application is notified that a
word is recognized, use SmGetFirmWords and SmGetInfirmWords to retrieve the list of words from
the reply message.
The engine continues decoding speech after a word is recognized during dictation. There are times
your application may need to halt the engine during dictation recognition; for example, while setting
new context or adding pronunciations. To do this, use SmHaltRecognizer, which will temporarily halt
recognition. A subsequent SmRecognizeNextWord call restarts the recognition process.
SmNewContext is called when dictation begins at a new location in the document. Context refers to
the previous and following words, which are used to decode the current word.
If the engine recognizes a word from a command vocabulary, the word is sent to the application in an
SM_RECOGNIZED_WORD reply message. The engine halts and waits for further instruction from
the application. Use SmGetFirmWords on SM_RECOGNIZED_WORD to get the recognized text
from the engine.
Correcting Errors
Correcting misrecognized words and improving recognition by updating personal data files are key
functions of dictation applications. Use SmPlayWords to play back previously spoken words or
phrases to the user. This can be of great help to the user in the correction process. Use
SmQueryAlternates to provide alternative choices when incorrectly recognized words have been
detected by the user. SmWordCorrection corrects a misrecognized word. It notifies the engine that a
word or sequence of words was corrected by the user. It can be used to update the user's text
vocabulary, word-usage model, and pronunciation pool.
Since the data that the engine stores can be resource intensive, use SmDiscardData to discard audio
and error correction data for recognized words that are not referenced again. This can conserve speech
recognition engine disk space requirements.
IBM SMAPI Reference
Starter Set APIs
Disconnecting from the Engine
When your application is closing down, you must disconnect and close the session with the speech
recognition engine. To do this, use SmDisconnect and SmClose.
IBM ViaVoice SDK for Windows
Chapter 3 Function Calls to the Speech
Recognition Engine
This chapter lists and describes the function calls that go directly to the speech recognition engine.
SmAddCallback
Purpose
SmAddCallback adds a single callback routine for the specified message.
Syntax
int SmAddCallback (char *reply_name, SmHandler *handler,
caddr_t client_data);
Parameters
reply_name
input - The name of the type of message.
handler
input -The function name of the routine that handles the message.
client_data
input - Data passed back to the handler when it is called.
Return Values
Sm_RC_EALLOC
SM_RC_ENOMEM
SM_RC_NOT_VALID_REQUEST
SM_RC_OK
SM_RC_SM_NOT_OPEN
Task Related Functions and Callbacks
SmDispatch
SmRemoveCallback
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmAddPronunciation
Purpose
SmAddPronunciation adds a new pronunciation.
This function provides the method for associating a pronunciation with a spelling.
The following restrictions apply when calling SmAddPronunciation:
.
The engine must be halted.
.
The utterance used to build the pronunciation must be complete.
.
If an SmAddPronunciation call fails and the call is immediately repeated with exactly the
same parameters, the engine will automatically apply more lenient threshold parameters the
second time. Reference “SmSet” on page 167 for a detailed description of the
SM_REJECTION_THRESHOLD parameter.
Note:
For this call to be valid, the application must first enable audio saving through
SmSet(SM_SAVE_AUDIO, TRUE).
Syntax
int SmAddPronunciation (char *spelling, char *pronunciation, long uttno,
short repetitions, long options, SM_MSG *reply);
Parameters
spelling
input -A null-terminated character string containing the spelling for the added pronunciation.
pronunciation
input - A null-terminated character string containing the pronunciation added and associated with
the given spelling. This parameter holds the phonetic spelling for the word, which indicates how
the word is pronounced.
uttno
input - Utterance number.
repetitions
input - Number of repetitions must be set to 1.
IBM ViaVoice SDK for Windows
SmAddPronunciation
options
input -The options are:
.
SM_ADD_PRONUNCIATION_ADD -Add a pronunciation.
.
SM_ADD_PRONUNCIATION_REPLACE - Delete existing pronunciations and replace
them with this new one.
reply
input/output - A pointer to a reply structure or to SmAsynchronous, indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_ADDWORD_LIMIT_EXCEEDED
SM_RC_BAD_ACOUSTICS
SM_RC_BAD_ADDWORD
SM_RC_ILLEGAL_SOUNDSLIKE
SM_RC_ILLEGAL_SPELLING
SM_RC_MISMATCHED_ACOUSTICS
SM_RC_NOT_ADDED
SM_RC_NOT_VALID_REQUEST
SM_RC_NOT_YET
SM_RC_SERVER_ERROR
SM_RC_SERVER_FILE_OPEN_ERROR
SM_RC_SERVER_FILE_READ_ERROR
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SM_RC_SERVER_FILE_WRITE_ERROR
SM_RC_SERVER_MALLOC_ERROR
Reply Structure Functions by Message Type
SM_ADD_PRONUNCIATION_REPLY
SmGetRc
SmGetSpelling
SmGetSpellings
Task Related Functions and Callbacks
SmQueryPronunciation
SmQueryPronunciations
SmRemovePronunciation
SmNaddPronunciationCallback
SmNqueryPronunciationCallback
SmNqueryPronunciationsCallback
SmNremovePronunciationCallback
IBM ViaVoice SDK for Windows
SmAddToVocab
SmAddToVocab
Purpose
SmAddToVocab adds words to a vocabulary.
This function adds words to predefined vocabularies or to a vocabulary previously created by
SmDefineVocab. SmAddToVocab can be used to dynamically change command vocabularies
within an application. If any of the specified words do not have an existing pronunciation, the call
returns the list of words without pronunciations. Missing pronunciations must be added by using the
SmAddPronunciation function. Pronunciations exist for all words in the predefined vocabularies
and for words added by the user. For a predefined vocabulary the words are added in the user's
personal pronunciation area of the vocabulary.
This call is valid only when the speech recognition engine is not decoding speech to text.
If a specified word does not exist in the current pool, the backup dictionary will be searched. If the
word is found in the backup dictionary, it will be added to the temporary pool, except that when
SmAddToVocab specifies a dictation vocabulary such as “text,” the word will be added to the
personal pool.
Syntax
int SmAddToVocab (char *vocab, short nvocwords, SM_VOCWORD *vocwords[],
SM_MSG *reply);
Parameters
vocab
input - The name of the vocabulary to which words are added.
nvocwords
input - The number of words added to the vocabulary, up to the limit defined by
SM_MAX_WORDS.
vocwords
input -The spellings of the words added to the vocabulary.
reply
input/output -The pointer to a reply structure or to SmAsynchronous, indicating that the call is
made asynchronously.
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_BAD_VOCAB
SM_RC_NOT_VALID_REQUEST
SM_RC_SERVER_FILE_OPEN_ERROR
SM_RC_SERVER_FILE_WRITE_ERROR
Reply Structure Functions by Message Type
SM_ADD_TO_VOCAB_REPLY
SmGetRc
SmGetVocabName
SmGetVocWords
Task Related Functions and Callbacks
SmDefineVocab
SmDisableVocab
SmEnableVocab
SmQueryAddedWords
SmQueryEnabledVocabs
SmQueryVocabs
SmQueryWord
SmRemoveFromVocab
SmUndefineVocab
IBM ViaVoice SDK for Windows
SmAddToVocab
SmNaddToVocabCallback
SmNdefineVocabCallback
SmNdisableVocabCallback
SmNenableVocabCallback
SmNqueryAddedWordsCallback
SmNqueryEnabledVocabsCallback
SmNqueryVocabsCallback
SmNqueryWordsCallback
SmNremoveFromVocabCallback
SmNundefineVocabCallback
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmApiVersionCheck
Purpose
SmApiVersionCheck verifies the current version of the SMAPI.
This function checks whether the version of the SMAPI used to compile the speech-aware
application is compatible with the API currently installed on the system. The reply message
contains the return code indicating the current status.
Syntax
int SmApiVersionCheck (char *caller_version, char **sm_version);
Parameters
caller_version
input - Indicates the version used to compile the application. The constant
SM_API_VERSION_STRING is used for the comparison check.
sm_version
output - The version of the SMAPI currently installed on the system.
Return Values
SM_RC_OK
SM_RC_WRONG_SM_VERSION
IBM ViaVoice SDK for Windows
SmAutoComplete
SmAutoComplete
Purpose
SmAutoComplete is called by a client application to request completions of a specified string.
Syntax
int SmAutoComplete (unsigned long flags, int max_depth, char *spelling,
SM_MSG *reply);
Parameters
flags
input - reserved
max_depth
input - maximum number of completions to return. Limited to SM_MAX_VOCWORDS.
spelling
input - string for which completions are requested
reply
input - The pointer to a reply structure or to SmAsynchronous indicating that the call is made
asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
SM_RC_SERVER_FILE_OPEN_ERROR
SM_RC_SERVER_FILE_READ_ERROR
SM_RC_SERVER_MALLOC_ERROR
Reply Structure Functions by Message Type
SM_AUTO_COMPLETE_REPLY
SmGetSpelling
SmGetSpellings
Task Related Functions and Callbacks
SmNautoCompleteCallback
Access Functions
SmGetSpelling (returns spelling)
SmGetSpellings (returns spellings array)
Remarks
SmAutoComplete will search active vocabularies, including topics, for completions of the given
string. If the number requested cannot be satisfied from the active vocabularies, the backup
dictionary will be searched.
IBM ViaVoice SDK for Windows
SmCancelPlayback
SmCancelPlayback
Purpose
SmCancelPlayback cancels the request to play back a message, utterance, or words.
This function cancels a play request from the SmPlayMessage, SmPlayUtterance, and
SmPlayWords functions.
Syntax
int SmCancelPlayback (SM_MSG *reply);
Parameters
reply
input/output -The pointer to a reply structure or to SmAsynchronous, indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
Reply Structure Functions by Message Type
SM_CANCEL_PLAYBACK_REPLY
SmGetRc
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Task Related Functions and Callbacks
SmPlayMessage
SmPlayUtterance
SmPlayWords
SmNcancelPlaybackCallback
SmNplayMessageCallback
SmNplayMessageStatusCallback
SmNplayUtteranceCallback
SmNplayUtteranceStatusCallback
SmNplayWordsCallback
SmNplayWordsStatusCallback
IBM ViaVoice SDK for Windows
SmClose
SmClose
Purpose
SmClose closes the SMAPI connection.
If the speech-aware application has not already called the SmDisconnect function to terminate the
connection with the speech recognition engine, the speech API does so before executing SmClose.
Syntax
int SmClose ();
Parameters
None.
Return Values
SM_RC_OK
SM_RC_SM_NOT_OPEN
Task Related Functions and Callbacks
SmDisconnect
SmNdisconnectCallback
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmConnect
Purpose
SmConnect connects to the speech recognition engine.
This function establishes a session with the speech recognition engine. The desired type of session
and other necessary information are provided by setting SMAPI attributes. Once a session is
established the session type cannot be changed. To change the session type, call SmDisconnect
then call SmConnect again.
Syntax
int SmConnect (int nargs, SmArg *Args, SM_MSG *reply);
Parameters
nargs
input - The number of arguments in the accompanying argument list.
Args
input - A set of arguments that indicate the parameters used to connect to the speech recognition
engine. Speech API arguments can also be set prior to an SmConnect call by using the SmSetArg
function, which specifies the parameter or attribute name and its value. The attributes passed to
this function determine the session type.
For details on establishing a speech session, see the SMAPI Developer's Guide. For details on the
attributes, see “SMAPI Attributes” on page 305.
reply
input - The pointer to a reply structure or to SmAsynchronous, indicating that the call is made
asynchronously.
IBM ViaVoice SDK for Windows
SmConnect
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_EUNEXP
SM_RC_INCOMPATIBLE_ENROLLMENT
SM_RC_NAVIGATOR_ALREADY_DEFINED
SM_RC_SM_NOT_OPEN
SM_RC_ALREADY_CONNECTED
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_BAD_ADDWORD
SM_RC_BAD_AP
SM_RC_BAD_AUDIO
SM_RC_BAD_DECO
SM_RC_BAD_DESCRIPTION
SM_RC_BAD_ENROLLID
SM_RC_BAD_PASSWORD
SM_RC_BAD_SCRIPT
SM_RC_BAD_TASKID
SM_RC_BAD_USERID
SM_RC_ENROLLID_EXISTS
SM_RC_ENROLLID_RUNNING
SM_RC_ENROLLMENT_NOT_COMPLETE
SM_RC_MISMATCHED_ALPHABET
SM_RC_MISMATCHED_LANGUAGE
SM_RC_MISMATCHED_SCRIPT
SM_RC_NOT_VALID_REQUEST
SM_RC_SERVER_ERROR
SM_RC_SEVER_FILE_OPEN_ERROR
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Reply Structure Functions by Message Type
SM_CONNECT_REPLY
SmGetMsgType
SmGetRc
SmGetService
SmGetSessionId
SmGetTask
SmGetTasks
SmGetUserId
Only recognition sessions:
SmGetCodepage
SmGetEnrollId
SmGetEnrollIds
SmGetLanguages
SmGetSessionId
SmGetUserId
SmGetUserIds
Task Related Functions and Callbacks
SmOpen
SmSetArg
SmNconnectCallback
IBM ViaVoice SDK for Windows
SmCorrectText
SmCorrectText
Purpose
SmCorrectText updates the user's voice model with a sequence of text the user considers correct.
This function provides the speech recognition engine with a sequence of correctly recognized text.
This text can be used to adapt the user's voice model, thereby improving future recognition of
dictated text.
Syntax
int SmCorrectText (short nwords, SM_WORD *words[], SM_MSG *reply);
Parameters
nwords
input - The number of words in the text sequence.
words
input - An array of pointers to the words of the text.
reply
input/output - The pointer to a reply structure indicating that the call is made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
SM_RC_SERVER_FILE_OPEN_ERROR
SM_RC_SERVER_FILE_WRITE_ERROR
Reply Structure Functions by Message Type
SM_CORRECT_TEXT_REPLY
SmGetRc
Task Related Functions and Callbacks
SmNewContext
SmRemovePronunciation
SmWordCorrection
SmNcorrectTextCallback
SmNnewContextCallback
SmNremovePronunciationCallback
SmNwordCorrectionCallback
IBM ViaVoice SDK for Windows
SmDefineGrammar
SmDefineGrammar
Purpose
SmDefineGrammar defines a grammar-based vocabulary.
This function dynamically defines a new vocabulary that can be enabled through the
SmEnableVocab function, along with dynamic command vocabularies defined through
SmDefineVocab. The vocabulary content is specified by a precompiled FSG file, produced by the
grammar compiler.
Like SmDefineVocab, SmDefineGrammar returns a list of grammar words that don't have
pronunciations. Unlike SmDefineVocab, if any pronunciation is missing, SmDefineGrammar
fails with a return code of SM_RC_NOT_INVOCAB, since recognition of a grammar network
with missing pronunciations is not well defined. Use SmGetVocWords to retrieve the list of
missing words.
If external lists are missing (for example, there was no SmDefineVocab before the
SmDefineGrammar), SmDefineGrammar will also fail. This time, the return code is
SM_RC_MISSING_EXTERN. The names of the external lists are returned as if they were words
without pronunciations, and can also be obtained with SmGetVocWords.
Since missing externs is really a program logic error, these are checked and returned before
determining if any words are missing pronunciations. So, if both externs and words are missing,
you first get SM_RC_MISSING_EXTERN. When that is fixed, you get
SM_RC_NOT_INVOCAB.
Note that pronunciations can be found in the user's personal pool, application-specific pools
(created by Dictionary Builder) or the base domain pool. If a specified word does not exist in the
current pool, the backup dictionary will be searched. If the word is found in the backup dictionary,
it will be added to the temporary pool, except that when SmAddToVocab specifies a dictation
vocabulary such as “text,” the word will be added to the personal pool.
Syntax
int SmDefineGrammar (char *vocab, char *grammar, long options,
SM_MSG *reply);
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Parameters
vocab
input -The name of the new grammar.
grammar
input - The fully qualified path name of the FSG file containing the compiled grammar.
options
flags include:
.
SM_PHRASE_ALLOW_SILENCES - allow inter-word silences within phrase.
.
SM_PHRASE_SHOW_SILENCES -silence indicated in returned phrase. Silences are
returned via the word spelling "" in the recognized phrase message.
.
SM_PHRASE_NO_SILENCES - don't allow inter-word silences
.
SM_PHRASE_ALLOW_INSERTIONS - allow insertions within phrase
.
SM_PHRASE_SHOW_INSERTIONS - insertions indicated in returned phrase. Insertions
are returned via an empty word spelling "" in the recognized phrase message.
.
SM_PHRASE_NO_INSERTIONS -don't allow insertions
Note:
These run-time flags override settings compiled in the FSG file.
reply
input/output -The pointer to a reply structure or to SmAsynchronous, indicating that the call is
made asynchronously.
Return Values
SM_RC_OK
SM_RC_MISSING_EXTERN
SM_RC_NOT_VALID_REQUEST
SM_RC_NOT_INVOCAB
SM_RC_BAD_VOCAB
SM_RC_SERVER_FILE_MALLOC_ERROR
SM_RC_SERVER_FILE_OPEN_ERROR
SM_RC_SERVER_FILE_READ_ERROR
IBM ViaVoice SDK for Windows
SmDefineGrammar
Reply Structure Functions by Message Type
SM_DEFINE_GRAMMAR_REPLY
SmNdefineGrammarCallback
SmGetVocabName
SmGetGrammarPath
SmGetVocWords
Task Related Functions and Callbacks
SmEnableVocab
SmUndefineGrammar
SmDisableVocab
SmNdisableVocabCallback
SmNdenableVocabCallback
SmNundefineVocabCallback
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmDefineVocab
Purpose
SmDefineVocab defines a new vocabulary.
This function dynamically creates a new vocabulary that can later be used by calling the
SmEnableVocab function. The vocabulary created by SmDefineVocab consists only of the words
specified in the call with all words receiving an equal voice model weighting. This function can be
used to dynamically create command vocabularies in an application. If any of the specified words
do not have an existing pronunciation, the call returns a list of words without pronunciations.
Pronunciations can be found in the predefined vocabulary and in the user's personal vocabulary.
Predefined vocabularies are not dynamic. Dynamic vocabularies are intended for command
vocabulary recognition.
SmDefineVocab takes more time to execute than SmEnableVocab and SmDisableVocab;
therefore, it is more efficient to define a vocabulary once and enable/disable frequently rather than
to define multiple times.
This call is valid only when the speech recognition engine is not decoding speech to text. For
examples of conditions when the engine is not decoding speech to text, see "Setting Up
Vocabularies" in the SMAPI Developer's Guide.
If a specified word does not exist in the current pool, the backup dictionary will be searched. If the
word is found in the backup dictionary, it will be added to the temporary pool, except that when
SmAddToVocab specifies a dictation vocabulary such as “text,” the word will be added to the
personal pool.
Syntax
int SmDefineVocab (char *vocab, short nvocwords, SM_VOCWORD *vocwords[],
SM_MSG *reply);
Parameters
vocab
input -The name of the new vocabulary.
nvocwords
input -The number of words in the new vocabulary. Limited to SM_MAX_VOCWORDS.
IBM ViaVoice SDK for Windows
SmDefineVocab
vocwords
input -The spellings of the words in the new vocabulary.
reply
input/output -The pointer to a reply structure or to SmAsynchronous, indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_BAD_VOCAB
SM_RC_NOT_VALID_REQUEST
SM_RC_SERVER_FILE_OPEN_ERROR
SM_RC_SERVER_FILE_WRITE_ERROR
Reply Structure Functions by Message Type
SM_DEFINE_VOCAB_REPLY
SmGetRc
SmGetVocabName
SmGetVocWords
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Task Related Functions and Callbacks
SmAddToVocab
SmDisableVocab
SmEnableVocab
SmQueryAddedWords
SmQueryEnabledVocabs
SmQueryVocabs
SmQueryWord
SmRemoveFromVocab
SmUndefineVocab
SmNaddToVocabCallback
SmNdefineVocabCallback
SmNdisableVocabCallback
SmNenableVocabCallback
SmNqueryAddedWordsCallback
SmNqueryEnabledVocabsCallback
SmNqueryVocabsCallback
SmNqueryWordsCallback
SmNremoveFromVocabCallback
SmNundefineVocabCallback
IBM ViaVoice SDK for Windows
SmDefineVocabEx
SmDefineVocabEx
Purpose
A new supported function, SmDefineVocabEx is an extension of the SMAPI function
SmDefineVocab. This function is called by a client application to define a vocabulary.
If a specified word does not exist in the current pool, the backup dictionary will be searched. If the
word is found in the backup dictionary, it will be added to the temporary pool, except that when
SmAddToVocab specifies a dictation vocabulary such as “text,” the word will be added to the
personal pool.
Syntax
int SmDefineVocabEx (char *vocab, void *data, int length, long options,
char *acoustic_id, char *poolname, SM_MSG *reply);
Parameters
vocab
input - The name of the vocabulary being defined.
data
Data used to define the new vocabulary. The form of the data depends on the value of the options
argument.
length
Length of data in bytes or number of elements
options
Options which specify how vocabulary is defined. These options are valid for almost all
vocabularies:
SM_VOCAB_REPLACE
Replace any currently defined vocabulary with the same name. This eliminates the need to
undefine the current vocabulary before defining the new one.
SM_VOCAB_GLOBAL
Active even if the client does not have focus.
SM_VOCAB_NOHALT
Engine does not halt after returning a command.
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
These options specify the format of the data:
SM_VOCAB_BINARY
The data is a buffer in binary format.
SM_VOCAB_FILE
The data is the name of a file.
SM_VOCAB_WORDS
The data is a list of words in ASCII format.
SM_VOCAB_VOCWORDS
The data is an array of pointers to SM_VOCWORD structures and the length field specifies
the number of elements in the array.
These options specify the type of vocabulary:
SM_VOCAB_COMMAND
Regular command vocabulary.
SM_VOCAB_TEXT
Acts like the “text” vocabulary but with no LM.
SM_VOCAB_FSG
Regular compiled grammar.
SM_VOCAB_PHRASE
Single-phrase grammar (for example, for Enrollment).
SM_VOCAB_SELECT
Select-phrase grammar (verb + any phrase)
SM_VOCAB_VERBFINAL
Verb follows selected phrase
In addition, the existing SM_PHRASE_ options may be set for grammars:
acoustic_id
Reserved: must be set to NULL
poolname
Reserved: must be set to NULL
reply
SmAsynchronous or pointer to reply structure.
IBM ViaVoice SDK for Windows
SmDefineVocabEx
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_BAD_VOCAB
SM_RC_MISSING_EXTERN
SM_RC_NOT_INVOCAB
SM_RC_NOT_VALID_REQUEST
Reply Structure Functions by Message Type
SM_DEFINE_VOCABULARY_REPLY
SmGetVocabName
SmGetVocabPath
SmGetVocWords
SmGetEventOptions
Task Related Functions and Callbacks
SmAddToVocab
SmDefineVocab
SmDefineGrammar
SmDisableVocab
SmEnableVocab
SmQueryAddedWords
SmQueryEnabledVocabs
SmQueryVocabs
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmQueryWord
SmRemoveFromVocab
SmUndefineVocab
SmNaddToVocabCallback
SmNdefineVocabCallback
SmNdisableVocabCallback
SmNenableVocabCallback
SmNqueryAddedWordsCallback
SmNqueryEnabledVocabsCallback
SmNqueryVocabsCallback
SmNqueryWordsCallback
SmNremoveFromVocabCallback
SmNundefineVocabCallback
SmNdefineVocabExCallback
Access Functions:
SmGetVocabName (Returns the name of the defined vocabulary.)
SmGetVocWords (Returns array of SPCH_VOCWORDs not successfully defined.)
SmGetVocabPath (Returns the name of file from input data argument.)
SmGetOptions (Returns options specified in input argument.)
Remarks:
Calling SmDefineVocabEx with options SM_VOCAB_VOCWORDS and
SM_VOCAB_COMMAND set is equivalent to calling SmDefineVocab. Calling
SmDefineVocabEx with options SM_VOCAB_FILE and SM_VOCAB_FSG set is equivalent to
calling SmDefineGrammar. Calling SmDefineVocabEx with options SM_VOCAB_WORDS and
SM_VOCAB_PHRASE set is equivalent to calling SmDefineGrammar with
SM_PHRASE_LITERAL set.
Only a few combinations of format and type option flags are currently supported:
SM_VOCAB_VOCWORDS + SM_VOCAB_COMMAND
SM_VOCAB_VOCWORDS + SM_VOCAB_TEXT
SM_VOCAB_FILE + SM_VOCAB_FSB
SM_VOCAB_WORDS + SM_VOCAB_PHRASE
The following options have not yet been implemented:
SM_VOCAB_REPLACE, SM_VOCAB_SELECT, SM_VOCAB_VERBFINAL
IBM ViaVoice SDK for Windows
SmDetachSessions
SmDetachSessions
Purpose
SmDetachSessions requests that one or more sessions detach.
This function requests all applications connected to the speech recognition engine to disconnect
from it. SmQuerySessions can be used to monitor the number of attached applications. The
disconnect request is in the form of the SM_REQUEST_DETACH reply message structure. The
engine does not force a session to disconnect and does not wait for a reply to the disconnect
request. This function can be used for switching users (or user ID, enroll ID, task).
Syntax
int SmDetachSessions (SM_MSG *reply);
Parameters
reply
input/output -The pointer to a reply structure or to SmAsynchronous, indicating that the call is
made asynchronously.
Return Values
SM_RC_OK
Reply Structure Functions by Message Type
SM_DETACH_SESSIONS_REPLY
SmGetRc
Task Related Functions and Callbacks
SmQuerySessions
SmNdetachRequestedCallback
SmNdetachSessionsCallback
SmNquerySessionsCallback
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmDisableVocab
Purpose
SmDisableVocab disables a defined vocabulary.
This function disables a vocabulary so it is no longer used by the speech recognition engine to
decode speech to text during a recognition session. Only the specified vocabulary is disabled. Any
other enabled vocabularies remain active.
This function is valid only when the speech recognition engine is not decoding speech to text. For
examples of conditions when the engine is not decoding speech to text, see "Setting Up
Vocabularies" in the SMAPI Developer's Guide.
Syntax
int SmDisableVocab (char *vocab, SM_MSG *reply);
Parameters
vocab
input - The name of the vocabulary to be disabled.
reply
input/output -The pointer to a reply structure or to SmAsynchronous, indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
IBM ViaVoice SDK for Windows
SmDisableVocab
For synchronous call and callbacks:
SM_RC_BAD_VOCAB
SM_RC_NOT_VALID_REQUEST
Reply Structure Functions by Message Type
SM_DISABLE_VOCAB_REPLY
SmGetRc
SmGetVocabName
Task Related Functions and Callbacks
SmAddToVocab
SmDefineVocab
SmEnableVocab
SmQueryAddedWords
SmQueryEnabledVocabs
SmQueryVocabs
SmQueryWord
SmRemoveFromVocab
SmUndefineVocab
SmNaddToVocabCallback
SmNdefineVocabCallback
SmNdisableVocabCallback
SmNenableVocabCallback
SmNqueryAddedWordsCallback
SmNqueryEnabledVocabsCallback
SmNqueryVocabsCallback
SmNqueryWordsCallback
SmNremoveFromVocabCallback
SmNundefineVocabCallback
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmDiscardData
Purpose
SmDiscardData discards audio and error-correction data.
This function discards audio data and error-correction information for recognized words that are
not referenced again, thus conserving speech recognition engine disk space (reference
“SmDisconnect” on page 74 for the SmNdiscardSessionData speech attribute used).
SmDiscardData works on the granularity of utterances (between SmMicOn and SmMicOff) and
discards utterance files owned by the application. Ownership is established by the application that
turned the microphone on to create the utterance. An application can guarantee ownership of its
data by toggling the microphone Off and On when it receives focus.
Syntax
int SmDiscardData (SM_MSG *reply);
Parameters
reply
input/output -The pointer to a reply structure or to SmAsynchronous, indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
IBM ViaVoice SDK for Windows
SmDiscardData
Reply Structure Functions by Message Type
SM_DISCARD_DATA_REPLY
SmGetRc
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmDiscardSpeechData
Purpose
SmDiscardSpeechData will be called by a client application to specify audio data that can be
deleted.
Syntax
int SmDiscardSpeechData (unsigned long flags, short ntags, long stags[],
long etags[], SM_MSG *reply);
Parameters
flags
Reserved.
ntags
Specifies number of tags in tag arrays
stags
Array of starting tags
etags
Array of ending tags
reply
SmAsynchronous or pointer to reply structure.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
IBM ViaVoice SDK for Windows
SmDiscardSpeechData
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
Reply Structure Functions by Message Type
SM_DISCARD_SPEECH_DATA_REPLY
SmGetStatus
Task Related Functions and Callbacks
SmQuerySpeechData
SmRestoreSpeechData
SmSaveSpeechData
SmNdiscardSpeechDataCallback
SmNquerySpeechDataCallback
SmNrestoreSpeechDataCallback
SmNsaveSpeechDataCallback
Access Functions:
SmGetFlags (Returns flags)
SmGetStatus (Returns status)
Remarks:
When this function is called, the engine will mark off sections .tag files associated with start/end tag
pairs. If an entire utterance is marked, the files associated with that utterance will be deleted. When
the speech data is saved (SmSaveSpeechData) those sections of remaining .wav files associated
with the tags marked as discarded will not be saved. Any tags marked as discarded will no longer be
usable.
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmDisconnect
Purpose
SmDisconnect disconnects from the speech recognition engine. This function closes the
communication connection with the speech recognition engine.
Any asynchronous engine messages left in the application message queue after the
SmDisconnect() call returns are no longer valid and should not be used in any further SMAPI calls.
If the application needs to reconnect to the engine after a call to SmDisconnect(), then any engine
messages remaining in the application message queue for the previously connected session must
be removed before calling SmConnect().
Syntax
int SmDisconnect (int nargs, SmArg *Args, SM_MSG *reply);
Parameters
nargs
input - The number of arguments in the accompanying argument list.
Args
input - A set of arguments that indicate default parameters for disconnecting from the speech
recognition engine. Different attributes can be specified depending on the type of session and the
disposition of current data. Arguments include:
In recognition sessions:
SmNdiscardSessionAdaptation
Reset the user's voice model to the state it was in before the decoding session.
SmNdiscardSessionData
Delete any data for this session.
SmNsaveSessionData
Keep the session data until the user re-initializes. (Default)
SmNsaveSessionAdaptation
Keep words added to the word-usage model during this session. (Default)
IBM ViaVoice SDK for Windows
SmDisconnect
reply
input/output -The pointer to a reply structure or to SmAsynchronous, indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
For synchronous call and callbacks:
SM_RC_BAD_ENROLLID
SM_BAD_SCRIPT
SM_RC_BAD_VALUE
SM_RC_ENROLLID_EXISTS
SM_RC_ENROLLID_RUNNING
SM_RC_NO_SPACE_TERM_ENROLL
SM_RC_NOT_VALID_REQUEST
SM_RC_SERVER_ERROR
Reply Structure Functions by Message Type
SM_DISCONNECT_REPLY
SmGetMsgType
SmGetRc
SmGetService
Task Related Functions and Callbacks
SmClose
SmNdisconnectCallback
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmDispatch
Purpose
SmDispatch receives one message and dispatches the callbacks.
This function provides the method through which callback functions are executed by Windows
applications. More specifically, this function receives one message from the speech recognition
engine and dispatches the appropriate callback routines, which were previously registered using
SmAddCallback, for the default connection.
Syntax
int SmDispatch (unsigned long ap_val);
Parameters
ap_val
input - Windows applications need to specify lParam here for ap_val.
Return Values
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_EINVAL
SM_RC_EMSGSIZE
SM_RC_ENOCONN
SM_RC_ENOHANDLES
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_ETIMEOUT
SM_RC_EUNEXP
SM_RC_EUNKMSG
SM_RC_NOT_OPEN
SM_RC_OK
Task Related Functions and Callbacks
SmAddCallback
SmRemoveCallback
IBM ViaVoice SDK for Windows
SmEnableVocab
SmEnableVocab
Purpose
SmEnableVocab enables a defined vocabulary.
This function enables a vocabulary to be used by the speech recognition engine to decode speech
to text during a recognition session. Currently enabled vocabularies are not disabled by this
function but remain enabled along with the newly enabled vocabulary. If currently enabled
vocabularies are to be disabled first, then an SmDisableVocab call must be made beforehand for
each vocabulary to be disabled.
This call is valid only when the speech recognition engine is not decoding speech to text.
Syntax
int SmEnableVocab (char *vocab, SM_MSG *reply);
Parameters
vocab
input - The name of the vocabulary to be enabled.
reply
input/output -The pointer to a reply structure or to SmAsynchronous, indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
For synchronous call and callbacks:
SM_RC_BAD_VOCAB
SM_RC_NOT_VALID_REQUEST
Reply Structure Functions by Message Type
SM_ENABLE_VOCAB_REPLY
SmGetRc
SmGetVocabName
Task Related Functions and Callbacks
SmAddToVocab
SmDefineVocab
SmDisableVocab
SmQueryAddedWords
SmQueryEnabledVocabs
SmQueryVocabs
SmQueryWord
SmRemoveFromVocab
SmUndefineVocab
SmNaddToVocabCallback
SmNdefineVocabCallback
SmNdisableVocabCallback
SmNenableVocabCallback
SmNqueryAddedWordsCallback
SmNqueryEnabledVocabsCallback
SmNqueryVocabsCallback
SmNqueryWordsCallback
SmNremoveFromVocabCallback
SmNundefineVocabCallback
IBM ViaVoice SDK for Windows
SmEventNotify
SmEventNotify
Purpose
SmEventNotify requests notification when the speech recognition engine completes decoding all
the audio dictated up to the time SmEventNotify was called.
This function causes the callback associated with the SmNeventSynchCallback to be called as
soon as decoding is completed for all the words dictated up to the time SmEventNotify was called.
If a callback is not used, the application is notified with the reply message structure
SM_EVENT_SYNCH sent by the speech recognition engine.
Syntax
int SmEventNotify (long event_id, long options, SM_MSG *reply);
Parameters
event_id
input - The event ID.
options
input - The options for the event, which can be logically OR'ed:
.
SM_EVENT_HALT_RECOGNITION - halt and switch to command recognition when event
is encountered (Default)
.
SM_EVENT_CONTINUE_RECOGNITION - notify application that event was encountered
and continue with recognition
.
SM_EVENT_FIRM_UP - process audio following event
.
SM_EVENT_DISCARD - discard audio following event (Default)
Notes:
SM_EVENT_HALT_RECOGNITION and SM_EVENT_CONTINUE_RECOGNITION cannot
be specified together.
SM_EVENT_FIRM_UP and SM_EVENT_DISCARD cannot be specified together.
reply
input/output -The pointer to a reply structure or to SmAsynchronous, indicating that the call is
made asynchronously.
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
Reply Structure Functions by Message Type
SM_EVENT_NOTIFY_REPLY
SmGetEventId
SmGetRc
SM_EVENT_SYNCH
SmGetEventId
SmGetEventOptions
SmGetRc
Task Related Functions and Callbacks
SmNeventNotifyCallback
SmNeventSynchCallback
IBM ViaVoice SDK for Windows
SmHaltRecognizer
SmHaltRecognizer
Purpose
SmHaltRecognizer temporarily halts recognition.
This function can be called when the speech recognition engine is decoding speech to text. Halting
recognition may be necessary, for example, to define and/or enable vocabularies to be used by the
engine during recognition. Recognition can be restarted with SmRecognizeNextWord.
Syntax
int SmHaltRecognizer (SM_MSG *reply);
Parameters
reply
input/output -The pointer to the reply structure or to the SmAsynchronous value.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
SM_RC_SERVER_ERROR
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Reply Structure Functions by Message Type
SM_HALT_RECOGNIZER_REPLY
SmGetNumberWordMsgs
SmGetRc
Task Related Functions and Callbacks
SmMicOff
SmMicOn
SmQuery
SmRecognizeNextWord
SmSet
SmNhaltRecognizerCallback
SmNmicOffCallback
SmNmicOnCallback
SmNqueryCallback
SmNrecognizeNextWordCallback
SmNrecognizedTextCallback
SmNrecognizedWordCallback
SmNsetCallback
SmNutteranceCompletedCallback
IBM ViaVoice SDK for Windows
SmMicOff
SmMicOff
Purpose
SmMicOff turns off the microphone.
This function turns off the microphone; however, in a recognition session, after the microphone is
turned off, the speech recognition engine continues speech to text decoding of words already
spoken. Depending on the speed and what is said before the microphone is turned off, this process
can take several seconds to complete.
Syntax
int SmMicOff (SM_MSG *reply);
Parameters
reply
input/output -The pointer to a reply structure or to SmAsynchronous, indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
For synchronous call and callbacks:
SM_RC_MIC_ALREADY_OFF
SM_RC_MIC_OFF_PENDING
SM_RC_NOT_VALID_REQUEST
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Reply Structure Functions by Message Type
SM_MIC_OFF_REPLY
SmGetRc
Task Related Functions and Callbacks
SmHaltRecognizer
SmMicOn
SmQuery
SmRecognizeNextWord
SmSet
SmNhaltRecognizerCallback
SmNmicOffCallback
SmNmicOnCallback
SmNqueryCallback
SmNrecognizeNextWordCallback
SmNrecognizedTextCallback
SmNrecognizedWordCallback
SmNsetCallback
SmNutteranceCompletedCallback
IBM ViaVoice SDK for Windows
SmMicOn
SmMicOn
Purpose
SmMicOn turns on the microphone.
In a recognition session, this function turns on the microphone and starts the audio stream. The
application must issue an SmRecognizedNextWord to start the engine decoding.
Syntax
int SmMicOn (SM_MSG *reply);
Parameters
reply
input/output -The pointer to the reply structure or to the SmAsynchronous value.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_BAD_AP
SM_RC_BAD_DECO
SM_RC_BUSY_LAST_UTTERANCE
SM_RC_BUSY_WORD_CORRECTION
SM_RC_ENROLLMENT_NOT_COMPLETE
SM_RC_MIC_ALREADY_ON
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SM_RC_MIC_OFF_PENDING
SM_RC_MIC_ON_PENDING
SM_RC_NO_SPACE_MIC_ON
SM_RC_NOT_VALID_REQUEST
Reply Structure Functions by Message Type
SM_MIC_ON_REPLY
SmGetRc
SmGetUtteranceNumber
During a recognition session:
SM_RECOGNIZED_TEXT
SmGetFirmWords
SmGetInfirmWords
SmGetRc
SmGetTimes
Task Related Functions and Callbacks
SmHaltRecognizer
SmMicOff
SmQuery
SmRecognizeNextWord
SmSet
SmNhaltRecognizerCallback
SmNmicOffCallback
SmNmicOnCallback
SmNqueryCallback
SmNrecognizeNextWordCallback
SmNrecognizedTextCallback
SmNrecognizedWordCallback
SmNsetCallback
SmNutteranceCompletedCallback
IBM ViaVoice SDK for Windows
SmNewContext
SmNewContext
Purpose
SmNewContext sends a new text context.
This function allows a change in text context sent to the speech recognition engine. This function
is usually called when text dictation begins at a new location in a document and can only be called
when the speech recognition engine is halted. Context refers to previous and following words,
which are used to decode the current word in a recognition session.
Syntax
int SmNewContext (short nwords, SM_WORD *words[], SM_MSG *reply);
Parameters
nwords
input - The number of words of context sent. Zero means no left context.
words
input - An array of pointers to the context words, ordered from left to right in the text.
reply
input/output -The pointer to the reply structure or to the SmAsynchronous value indicating that
the call is made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
Reply Structure Functions by Message Type
SM_NEW_CONTEXT_REPLY
SmGetRc
Task Related Functions and Callbacks
SmCorrectText
SmCorrectTextCancel
SmRemovePronunciation
SmWordCorrection
SmNcorrectTextCallback
SmNcorrectTextCancelCallback
SmNnewContextCallback
SmNremovePronunciationCallback
SmNwordCorrectionCallback
IBM ViaVoice SDK for Windows
SmOpen
SmOpen
Purpose
SmOpen opens the SMAPI.
This function establishes a SMAPI connection and initializes values in a connection structure.
Syntax
int SmOpen (int nargs, SmArg *Args);
Parameters
nargs
input - The number of arguments in the accompanying argument list.
Args
input - A set of arguments that indicate default parameters for the SMAPI connection. They are
stored in a connection structure for the speech-aware application. The values in the structure are
used to set up the session with the speech recognition engine. SMAPI attributes can also be set by
using the SmSetArg function, which specifies the attribute name and its value.
For details on establishing a speech session, see the SMAPI Developer's Guide. For details on the
attributes, reference “SMAPI Attributes” on page 305.
Return Values
SM_RC_EALLOC
SM_RC_ENOMEM
SM_RC_NAVIGATOR_ALREADY_DEFINED
SM_RC_OK
SM_RC_ALREADY_CONNECTED
SM_RC_ALREADY_OPENED
For synchronous call and callbacks:
SM_RC_OPEN_SYNCH_QUEUE_FAILED
SM_RC_NOT_VALID_REQUEST
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Task Related Functions and Callbacks
SmConnect
SmSetArg
SmNconnectCallback
IBM ViaVoice SDK for Windows
SmPlayMessage
SmPlayMessage
Purpose
SmPlayMessage plays back a prerecorded audio file.
This function allows the user to play a prerecorded audio file. After the speech-aware application
requests a playback, it can call SmGetStatus to retrieve the last playback status, which can be one
of the following:
SM_STAT_BAD_AUDIO
The connection to the audio source was lost during playback.
SM_STAT_PLAY_START
The message has started playing.
SM_STAT_PLAY_STOP
The message has stopped playing.
Possible return values passed to the SmNplayMessageStatusCallback are:
.
SM_RC_OK
.
SM_RC_BAD_AUDIO
.
SM_RC_PLAY_OPEN_ERROR
The following restrictions apply when calling SmPlayMessage:
.
Microphone must be off.
.
Speech recognition engine must not be decoding speech to text. In other words, the application
must have received SM_UTTERANCE_COMPLETED from the engine.
Syntax
int SmPlayMessage (char *message_name, char *language, SM_MSG *reply);
Parameters
message_name
input - The fully qualified name of an audio file in IBM ViaVoice format, which is 8-bit (mono) u-
Law PCM at 11.025kHz, 8.0kHz or 22.05kHz. These audio files can be created by dictating the
message and saving to a file in the IBM ViaVoice user path.
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
language
input -The name of the language played.
reply
input/output -The pointer to the reply structure or to the SmAsynchronous value indicating that
the call is made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_BAD_LANGUAGE
SM_RC_BAD_MESSAGE
SM_RC_NOT_VALID_REQUEST
SM_RC_NOT_WHILE_MIC_ON
Reply Structure Functions by Message Type
SM_PLAY_MESSAGE_REPLY
SmGetRc
SM_PLAY_MESSAGE_STATUS
SmGetMsgName
SmGetRc
SmGetStatus
IBM ViaVoice SDK for Windows
SmPlayMessage
Task Related Functions and Callbacks
SmCancelPlayback
SmPlayUtterance
SmPlayWords
SmNcancelPlaybackCallback
SmNplayMessageCallback
SmNplayMessageStatusCallback
SmNplayUtteranceCallback
SmNplayUtteranceStatusCallback
SmNplayWordsCallback
SmNplayWordsStatusCallback
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmPlayUtterance
Purpose
SmPlayUtterance plays back a spoken utterance.
This function allows an utterance or a portion of an utterance previously spoken during dictation or
enrollment to be played back to the user as an error-correction aid. For a monitored enrollment
session, an utterance corresponds to a sentence of an enrollment script and, for a recognition
session, it corresponds to any word spoken between SmMicOn and subsequent SmMicOff.
After the speech-aware application requests a playback it can call SmGetStatus to retrieve the last
playback status, which can be one of the following:
SM_STAT_BAD_AUDIO
The connection to the audio source was lost during playback.
SM_STAT_PLAY_START
The utterance has started playing.
SM_STAT_PLAY_STOP
The utterance has stopped playing.
Possible return values passed to the SmNplayUtteranceStatusCallback are:
.
SM_RC_OK
.
SM_RC_BAD_AUDIO
.
SM_RC_PLAY_OPEN_ERROR
The following restrictions apply when calling SmPlayUtterance:
.
Microphone must be off.
.
Speech recognition engine must not be decoding speech to text. In other words, the application
must have received SM_UTTERANCE_COMPLETED from the engine.
Note:
For this call to be valid, the application must first enable audio saving through
SmSet(SM_SAVE_AUDIO, TRUE).
IBM ViaVoice SDK for Windows
SmPlayUtterance
Syntax
int SmPlayUtterance(long uttno, long begtime, long endtime, SM_MSG *reply);
Parameters
uttno
input -The utterance number to play back. The current utterance number can be extracted from
SM_MIC_ON_REPLY with SmGetUtteranceNumber.
begtime
input - Reserved. Must be set to 0.
endtime
input - Reserved. Must be set to 0.
reply
input/output -The pointer to a reply structure or to SmAsynchronous, indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
SM_RC_NOT_WHILE_MIC_ON
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Reply Structure Functions by Message Type
SM_PLAY_UTTERANCE_REPLY
SmGetRc
SM_PLAY_UTTERANCE_STATUS
SmGetRc
SmGetStatus
SmGetUtteranceNumber
Task Related Functions and Callbacks
SmCancelPlayback
SmPlayMessage
SmPlayWords
SmNcancelPlaybackCallback
SmNplayMessageCallback
SmNplayMessageStatusCallback
SmNplayUtteranceCallback
SmNplayUtteranceStatusCallback
SmNplayWordsCallback
SmNplayWordsStatusCallback
IBM ViaVoice SDK for Windows
SmPlayWords
SmPlayWords
Purpose
SmPlayWords plays back spoken words.
This function allows a previously spoken word or collection of words to be played back to the user
as an error correction aid.
The SmPlayWords call generates one or more SM_PLAY_WORDS_STATUS messages. When
this message is received, the application can call SmGetStatus to retrieve the status of the last
playback, which can be one of the following:
SM_STAT_BAD_AUDIO
The connection to the audio source was lost during playback.
SM_STAT_BAD_TAG
An invalid word (tag) was specified for the played word.
SM_STAT_PLAY_START
The word has started playing.
SM_STAT_PLAY_STOP
The word has stopped playing.
Possible return values passed to the SmNplayWordsStatusCallback are:
.
SM_RC_OK
.
SM_RC_BAD_TAG
.
SM_RC_PLAY_OPEN_ERROR
The following restrictions apply when calling SmPlayWords:
.
Microphone must be off.
.
Speech recognition engine must not be decoding speech to text. In other words, the application
must have received SM_UTTERANCE_COMPLETED from the engine.
Note:
For this call to be valid, the application must first enable audio saving through
SmSet(SM_SAVE_AUDIO, TRUE).
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Syntax
int SmPlayWords (short ntags, long tags[], long options, SM_MSG *reply);
Parameters
ntags
input - The number of words (tags) to play back.
tags
input - The array of word tags.
options
input - One of the following:
SM_PLAY_WORDS_CONTIGUOUS
When playing multiple words, return a single SM_PLAY_WORDS_STATUS message at the
beginning (SM_STAT_PLAY_START) of each word played, and return a single message
(SM_STAT_PLAY_STOP) after all words have been played. This is the default.
SM_PLAY_WORDS_SAVE_WAVEFILE
Instead of sending audio to the output device, this flag saves the audio data as a wave(WAV)
file. The name of the wave file must be set via an SmSetDirectory call prior to calling the
SmPlayWords function. If the SM_PLAY_WORDS_WITH _SILENCE flag is also set, then
the entire utterance(s) corresponding to the input tag array will be written to the wave file.
SM_PLAY_WORDS_SEPARATE
When playing multiple words, return separate SM_PLAY_WORDS_STATUS messages at the
beginning (SM_STAT_PLAY_START) of each word played and a single message
(SM_STAT_PLAY_STOP) when the entire list of tags has been played. If playback is
canceled, the SM_STAT_PLAY_STOP is also sent to indicate completion of the interrupted
playback request.
SM_PLAY_WORDS_WITH_SILENCE
When playing multiple words, playback the silence between words. The default is to play only
the non-silence portion of recognized words.
reply
input/output -The pointer to a reply structure or to SmAsynchronous, indicating that the call is
made asynchronously.
IBM ViaVoice SDK for Windows
SmPlayWords
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_BAD_TAG
SM_RC_NOT_VALID_REQUEST
SM_RC_NOT_WHILE_MIC_ON
Reply Structure Functions by Message Type
SM_PLAY_WORDS_REPLY
SmGetRc
SM_PLAY_WORDS_STATUS
SmGetRc
SmGetStatus
SmGetTags
Task Related Functions and Callbacks
SmCancelPlayback
SmPlayMessage
SmPlayUtterance
SmQueryWord
SmWordCorrection
SmNcancelPlaybackCallback
SmNplayMessageCallback
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmNplayMessageStatusCallback
SmNplayUtteranceCallback
SmNplayUtteranceStatusCallback
SmNplayWordsCallback
SmNplayWordsStatusCallback
SmNqueryAddedWordsCallback
IBM ViaVoice SDK for Windows
SmQuery
SmQuery
Purpose
SmQuery queries a speech recognition engine parameter.
This function queries the value of the specified speech recognition engine parameter. Call the
SmGetItemValue function to extract the queried value.
Syntax
int SmQuery (short item, SM_MSG *reply);
Parameters
item
input - The parameter queried, which can be one of the following:
SM_API_DEBUG
Values include the following: 0 is debugging off, 1 to 5 provide progressively more debug
information. A value of 1 or 2 provides flow of control information.
SM_API_DISPLAY
Reserved
SM_API_LOG
Reserved
SM_API_TIMING
Reserved
SM_AUDIO_CONFIGURATION
(Not applicable to Windows. Instead use Audio Setup program.)
Query the input source of the audio hardware where audio data is collected. The returned value
is bit mapped and can be any combination of the following values:
. SM_AUDIO_INPUT_MIC_HI_GAIN
. SM_AUDIO_INPUT_MIC_LO_GAIN
. SM_AUDIO_INPUT_LINE_LEFT
. SM_AUDIO_INPUT_LINE_RIGHT
. SM_AUDIO_INPUT_VARIABLE_GAIN
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
. SM_AUDIO_OUTPUT_LINE_LEFT
. SM_AUDIO_OUTPUT_LINE_RIGHT
. SM_AUDIO_OUTPUT_INTERNAL_SPEAKER
. SM_AUDIO_OUTPUT_VARIABLE_GAIN
Refer to the SMLIMITS.H file for bounds on input and output values.
SM_AUDIO_DEVICE
Query the type of audio hardware. Return values include the following:
. SM_ACPA_AUDIO - Reserved
. SM_PERSONAL_DICTATION_AUDIO
. SM_SYSTEM_AUDIO -native audio system for hardware/operating systems.
SM_AUDIO_INPUT_MODE
(Not applicable to Windows. Instead use Audio Setup program.)
Query the input source of the audio hardware where audio data is collected. We suggest you
use the supplied AUDIO.DLL instead. The returned value is bit mapped and can be any one of
the following values:
. SM_AUDIO_INPUT_LINE_LEFT
. SM_AUDIO_INPUT_LINE_RIGHT
. SM_AUDIO_INPUT_MIC_HI_GAIN
. SM_AUDIO_INPUT_MIC_LO_GAIN
SM_AUDIO_INPUT_GAIN
(Not applicable to Windows. Instead use Audio Setup program.)
If supported by underlying audio, this parameter allows you to query current gain setting.
SM_AUDIO_OUTPUT_GAIN
(Not applicable to Windows. Instead use Audio Setup program.)
If supported by underlying audio, this parameter allows you to query current gain setting.
IBM ViaVoice SDK for Windows
SmQuery
SM_AUDIO_OUTPUT_MODE
(Not applicable to Windows. Instead use Audio Setup program.)
If supported by underlying audio, this bit value indicates the current output destination. We
suggest you use the supplied audio.dll instead. The returned value can be any one of the
following values:
. SM_AUDIO_OUTPUT_LINE_LEFT
. SM_AUDIO_OUTPUT_LINE_RIGHT
. SM_AUDIO_OUTPUT_LINE_INTERNAL_SPEAKER
SM_COMPLETE_COMMAND_TIMEOUT
These timeout parameters are used to control the behavior of finite state grammars. In
particular, they specify how much silence is needed at the end of commands before the engine
will make a recognition decision to accept or reject the command. The amount of silence
required to accept or reject a phrase that is unambiguously complete. Default value is 25
(csecs). Can be overridden by task dependent .par values.
SM_ENABLE_EXCLUSIVE_VOCABS
Query the calling application's vocabularies. The value is either TRUE (1) for enabled, or
FALSE (0) for disabled.
SM_ENGINE_DEBUG
Reserved.
SM_ENGINE_DISPLAY
Reserved.
SM_REJECTION_THRESHOLD
Returns value from SM_MIN_REJECTION_THRESHOLD to
SM_MAX_REJECTION_THRESHOLD (reference “SmSet” on page 167 for a detailed
description of the SM_REJECTION_THRESHOLD parameter).
SM_ENGINE_LOG
Reserved.
SM_NOTIFY_AUDIO_LEVEL
Query the returning of audio-level data during recognition or enrollment. The value is either
TRUE (1) or FALSE (0).
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SM_NOTIFY_COMMAND_WORD
Query whether the application is notified when a command word is recognized by having the
engine send a SM_COMMAND_WORD reply message. The value is either TRUE (1) or
FALSE (0).
SM_NOTIFY_ENGINE_STATE
Query whether the application is notified of a speech recognition engine state change. The
value is either TRUE (1) or FALSE (0).
SM_NOTIFY_FOCUS_STATE
Query whether the application is notified of a speech focus state change. The value is either
TRUE (1) or FALSE (0).
SM_NOTIFY_MIC_STATE
Query whether the application is notified of a microphone state change. The value is either
TRUE (1) or FALSE (0).
SM_PARTIAL_COMMAND_TIMEOUT
These timeout parameters are used to control the behavior of finite state grammars. In
particular, they specify how much silence is needed at the end of commands before the engine
will make a recognition decision to accept or reject the command. The amount of silence
required to accept or reject a phrase that is both partially complete and complete. Default value
is 250 (csecs). It can be overridden by task dependent .par value.
For example, consider the grammar:
command = move up 3 move up five
Now consider the following acoustic scenarios:
1.MOVE
2.MOVE UP
3.MOVE UP FIVE
1.The engine will accept silences up to 0.5 seconds, waiting for the UP, before rejecting
the phrase as incomplete.
2.The engine will accept silences up to 0.5 seconds, waiting for the optional FIVE, before
accepting the phrase MOVE UP.
3.Then engine will wait only 0.1 seconds after the FIVE to accept the phrase.
For the example given, it seems that you would like to increase the
SM_PARTIAL_COMMAND_TIMEOUT in order to allow longer pauses within phrases.
IBM ViaVoice SDK for Windows
SmQuery
Note that increasing this parameter will also increase the decision time for "ambiguously
complete" phrases.
SM_REDUCED_CPU_MODE
Query the CPU mode of the speech recognition engine. The value is either TRUE (1) for
reduced CPU mode, or FALSE (0) for normal CPU mode. See “SmGetEngineState” on
page 205.
SM_SAVE_AUDIO
Query whether recorded audio is being saved during recognition. The value is either TRUE (1)
or FALSE (0).
SM_ENGINE_TIMING
Reserved.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_BAD_MODE
SM_RC_NOT_YET
SM_RC_EXISTS_IN_NOTIFY
SM_RC_NOT_IN_NOTIFY
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Reply Structure Functions by Message Type
SM_QUERY_REPLY
SmGetItemValue
SmGetRc
Task Related Functions and Callbacks
SmHaltRecognizer
SmMicOff
SmMicOn
SmRecognizeNextWord
SmSet
SmNhaltRecognizerCallback
SmNmicOffCallback
SmNmicOnCallback
SmNqueryCallback
SmNrecognizeNextWordCallback
SmNrecognizedTextCallback
SmNrecognizedWordCallback
SmNsetCallback
SmNutteranceCompletedCallback
IBM ViaVoice SDK for Windows
SmQueryAddedWords
SmQueryAddedWords
Purpose
SmQueryAddedWords queries added words.
This function requests a list of all words that have been added to vocabularies of the currently
active session.
Syntax
int SmQueryAddedWords (char *vocab, SM_MSG *reply);
Parameters
vocab
input - The name of the vocabulary to query.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_BAD_VOCAB
SM_RC_NOT_VALID_REQUEST
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Reply Structure Functions by Message Type
SM_QUERY_ADDED_WORDS_REPLY
SmGetRc
SmGetWords
Task Related Functions and Callbacks
SmAddToVocab
SmDefineVocab
SmDisableVocab
SmEnableVocab
SmNaddToVocabCallback
SmNdefineVocabCallback
SmNdisableVocabCallback
SmNenableVocabCallback
SmNplayWordsCallback
SmNplayWordsStatusCallback
SmNqueryAddedWordsCallback
SmNqueryEnabledVocabsCallback
SmNqueryVocabsCallback
SmNqueryWordsCallback
SmNremoveFromVocabCallback
SmNundefineVocabCallback
SmNwordCorrectionCallback
SmPlayWords
SmQueryAddedWords
SmQueryEnabledVocabs
SmQueryVocabs
SmQueryWord
SmRemoveFromVocab
SmUndefineVocab
SmWordCorrection
IBM ViaVoice SDK for Windows
SmQueryAddedWordsEx
SmQueryAddedWordsEx
Purpose
SmQueryAddedWordsEx extends SmQueryAddedWords. This new function accepts an
argument which specifies a starting point. It will return words beginning from this starting point up
to the limit SM_MAX_WORDS (500). If the specified starting point is greater than the number of
added words, no words will be returned.
Syntax
int SmQueryAddedWordsEx (unsigned long flags, unsigned long start,
char *vocab, SM_MSG *reply);
Parameters
flags
Reserved.
start
Specifies O-origin starting place.
vocab
Specifies the name of the vocabulary to query.
reply
SmAsynchronous or the pointer to a reply structure.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
SM_RC_BAD_VOCAB
Reply Structure Functions by Message Type
SM_QUERY_ADDED_WORDS_REPLY
SmGetWords
Task Related Functions and Callbacks
SmAddToVocab
SmDefineVocab
SmDisableVocab
SmEnableVocab
SmNaddToVocabCallback
SmNdefineVocabCallback
SmNdisableVocabCallback
SmNenableVocabCallback
SmNplayWordsCallback
SmNplayWordsStatusCallback
SmNqueryAddedWordsCallback
SmNqueryAddedWordsExCallback
SmNqueryEnabledVocabsCallback
SmNqueryVocabsCallback
SmNqueryWordsCallback
SmNremoveFromVocabCallback
SmNundefineVocabCallback
SmNwordCorrectionCallback
SmPlayWords
SmQueryAddedWords
SmQueryEnabledVocabs
SmQueryVocabs
SmQueryWord
SmRemoveFromVocab
SmUndefineVocab
SmWordCorrection
IBM ViaVoice SDK for Windows
SmQueryAddedWordsEx
Access Functions:
SmGetWords
Remarks:
Calling SmQueryAddedWords is equivalent to calling SmQueryAddedWordsEx with a start
argument of 0.
If there are more added words than the limit SM_MAX_WORDS, this function may be called
repeatedly, specifying a start argument of 0 the first time and incrementing the start argument by
the number of words returned. When 0 words are returned, all added words have been retrieved.
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmQueryAlternates
Purpose
SmQueryAlternates requests a list of alternative words.
This function requests a list of alternative choices for a firm word or a group of firm words that has
been incorrectly recognized. Errors are usually one-for-one substitutions, in which case only one
word needs to be specified on the call to SmGetAlternates. A word may, however, be recognized
incorrectly as two or more words. In that case, two or more words might need to be specified in
order to get an alternative list containing the correct word.
The following restrictions apply when calling SmQueryAlternates:
.
Microphone must be off
.
Speech recognition engine must not be decoding speech to text. In other words, the application
must have received SM_UTTERANCE_COMPLETED from the engine.
.
SM_SAVE_AUDIO must be enabled with SmSet.
Note:
For this call to be valid, the application must first enable audio saving through
SmSet(SM_SAVE_AUDIO, TRUE).
Syntax
int SmQueryAlternates (short ntags, long tags[], SM_MSG *reply);
Parameters
ntags
input - The number of words (tags) for which alternatives are requested.
tags
input -The tags of the word for which alternatives are requested.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
IBM ViaVoice SDK for Windows
SmQueryAlternates
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
Reply Structure Functions by Message Type
SM_QUERY_ALTERNATES_REPLY
SmGetAlternates
SmGetRc
SmGetTags
Task Related Functions and Callbacks
SmNqueryAlternatesCallback
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmQueryBinary
Purpose
SmQueryBinary queries the value of a specified speech recognition engine parameter.
This function is used instead of SmQuery to query values of arbitrary length and data type.
Syntax
int SmQueryBinary (short item, SM_MSG *reply);
Parameters
item
input - The parameter to be queried, which can be any of the following:
. SM_AUDIO_SOURCE -Specifies querying value in audio library.
. SM_MNR_VALUE -Specifies querying mnr value.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
If item is SM_AUDIO_SOURCE return values depend on audio library implementation of
AudioQuerySource.
If item is SM_MNR_VALUE return mnr value.
Reply Structure Functions by Message Type
SM_QUERY_BINARY_REPLY
SmGetRc
SmGetBinaryItemValue
Task Related Functions and Callbacks
SmSetBinary
SmNsetBinaryCallback
IBM ViaVoice SDK for Windows
SmQueryDefault
SmQueryDefault
Purpose
SmQueryDefault queries the default value for a user, enrollment, task ID speech attribute, or the
default topics.
Syntax
int SmQueryDefault (long item, SM_MSG *reply);
Parameters
item
input -Type of default ID speech attribute. Valid values include the following:
. SM_DEFAULT_USERID
. SM_DEFAULT_ENROLLID
. SM_DEFAULT_TASK
. SM_DEFAULT_TOPICS
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_OK
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Reply Structure Functions by Message Type
SM_QUERY_DEFAULT_REPLY
SmGetEnrollId
SmGetEnrollIds
SmGetRc
SmGetScripts
SmGetTask
SmGetTasks
SmGetUserId
SmGetUserIds
SmGetDefaultTopics
Task Related Functions and Callbacks
SmConnect
SmOpen
SmSetDefault
SmQueryUserDefault
SmSetUserDefault
SmNqueryDefaultCallback
SmNqueryUserDefaultCallback
SmNsetDefaultCallback
SmNsetUserDefaultCallback
Remarks:
The default enrollid, taskid, and topics are stored on a per-user basis. SmQueryDefault called
with an item value of SM_DEFAULT_USERID will return the value of the default userid. It can be
accessed in the reply structure using the function SmGetUserId or SmGetUserIds.
SmQueryDefault called with other item values will return default enrollid, taskid, or topics for the
default userid. The value of the default enrollid can be accessed in the reply structure using the
functions SmGetEnrollId or SmGetEnrollIds. The value of the default taskid can be accessed in
the reply structure using the functions SmGetTask or SmGetTasks. The value of the default topics
can be accessed in the reply structure using the function SmGetDefaultTopics. Since multiple
default topics can be associated with a userid the default topics will be returned concatenated in a
blank delimited string. To query the default enrollid, task or topics for a user other than the default
user, the function SmQueryUserDefault is provided.
IBM ViaVoice SDK for Windows
SmQueryEnabledVocabs
SmQueryEnabledVocabs
Purpose
SmQueryEnabledVocabs queries currently enabled vocabularies.
This function obtains a list of all currently enabled vocabularies.
Syntax
int SmQueryEnabledVocabs (SM_MSG *reply);
Parameters
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
Reply Structure Functions by Message Type
SM_QUERY_ENABLED_VOCABS_REPLY
SmGetRc
SmGetVocabList
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Task Related Functions and Callbacks
SmAddToVocab
SmDefineVocab
SmDisableVocab
SmEnableVocab
SmQueryAddedWords
SmQueryVocabs
SmQueryWord
SmRemoveFromVocab
SmUndefineVocab
SmNaddToVocabCallback
SmNdefineVocabCallback
SmNdisableVocabCallback
SmNenableVocabCallback
SmNqueryAddedWordsCallback
SmNqueryEnabledVocabsCallback
SmNqueryVocabsCallback
SmNqueryWordsCallback
SmNremoveFromVocabCallback
SmNundefineVocabCallback
IBM ViaVoice SDK for Windows
SmQueryEnrollIds
SmQueryEnrollIds
Purpose
SmQueryEnrollIds queries user enrollment IDs. This function returns a list of the enrollment IDs
previously generated for a user by an enrollment procedure. Each time a user enrolls for the
recognition system a new enrollment ID is generated for that user. When speech recognition is
performed, one of the enrollment IDs from the user's enrollment ID list must be specified for the
SmConnect function.
SmQueryEnrollIds returns the sample rate associated with each queried enrollid. The new access
function SmGetSampleRates is provided to access the array of sample rates.
Syntax
int SmQueryEnrollIds (char *user_id, char *enroll_id, char *language,
SM_MSG *reply);
Parameters
user_id
input -The name of the user whose enrollment ID list is to be returned.
enroll_id
input - The enrollment ID queried, or NULL if all enrollments are queried.
language
input -The language for the enrollment ID, or NULL if all languages are queried.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_BAD_ENROLLID
SM_RC_BAD_USERID
SM_RC_SERVER_MALLOC_ERROR
Reply Structure Functions by Message Type
SM_QUERY_ENROLLIDS_REPLY
SmGetAlphabets
SmGetDescriptions
SmGetEnrollIds
SmGetLanguages
SmGetPercentages
SmGetRc
SmGetSampleRates
SmGetScripts
SmGetStates
Task Related Functions and Callbacks
SmNrequestNewEnrollIdCallback
IBM ViaVoice SDK for Windows
SmQueryLanguages
SmQueryLanguages
Purpose
SmQueryLanguages queries the available languages.
This function returns a list of available languages that can be used to initialize the speech
recognition engine.
Syntax
int SmQueryLanguages (SM_MSG *reply);
Parameters
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_SERVER_MALLOC_ERROR
Reply Structure Functions by Message Type
SM_QUERY_LANGUAGES_REPLY
SmGetDescriptions
SmGetLanguages
SmGetRc
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Task Related Functions and Callbacks
SmNqueryLanguagesCallback
IBM ViaVoice SDK for Windows
SmQueryPhraseAlternatives
SmQueryPhraseAlternatives
Purpose
SmQueryPhraseAlternatives will be called by a client application to request the next recognition
phrase alternative for a grammar vocabulary.
Syntax
int SmQueryPharaseAlternatives (unsigned long flags, SM_MSG *reply);
Parameters
flags
Reserved.
reply
The pointer to a reply structure or to SmAsynchronous indicating that the call is made
asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Reply Structure Functions by Message Type
SM_QUERY_PHRASE_ALTERNATIVES_REPLY
SmGetVocabName
SmGetFirmWords
SmGetAnnotations
SmGetWordTimes
SmGetFlags
Task Related Functions and Callbacks
SmNqueryPhraseAlternativesReply
Access Functions
SmGetFirmWords
SmGetFlags
SmGetVocabName
SmGetAnnotations
SmGetWordTimes
Remarks:
This function is called repeatedly to get recognition phrase alternatives. A new flag will be defined
for the flag field of the SM_QUERY_PHRASE_ALTERNATIVES_REPLY message. When this
flag is set, it indicates no more alternatives are available.
SM_PHRASE_NO_ALTERNATIVES_AVAILABLE
This flag can be accessed by calling the access function SmGetFlags against the
SM_QUERY_PHRASE_ALTERNATIVES_REPLY message. The maximum phrase alternatives
calculated is 10.
The Nbest feature will be activated by a parameter in the parameter file (.par).
DC - nbest
This parameter will specify the number of alternatives to be recognized by the engine. Valid values
are 1-10. Note that this is a global setting. If this parameter is set, the engine will calculate
alternatives for all clients connected to the engine.
IBM ViaVoice SDK for Windows
SmQueryPronunciation
SmQueryPronunciation
Purpose
SmQueryPronunciation queries the existence of a pronunciation.
This function provides a method for a requesting application to determine whether an associated
pronunciation exists for a given spelling. This query is applied to the pronunciations that have been
added to the user's personal pronunciation pool and the temporary pool. The query returns if it
found the pronunciation, but will not tell you where the pronunciations exist.
If a specified word does not exist in the current pool, the backup dictionary will be searched. If the
word is found in the backup dictionary, it will be added to the temporary pool, except that when
SmAddToVocab specifies a dictation vocabulary such as “text,” the word will be added to the
personal pool.
Syntax
int SmQueryPronunciation (char *spelling, SM_MSG *reply );
Parameters
spelling
input -A spelling for which a pronunciation is sought.
reply
input/output - A pointer to a reply structure or to SmAsynchronous indicating that the call is made
asynchronously.
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_NOT_INVOCAB
SM_RC_NOT_VALID_REQUEST
Reply Structure Functions by Message Type
SM_QUERY_PRONUNCIATION_REPLY
SmGetRc
SmGetSpelling
SmGetSpellings
Task Related Functions and Callbacks
SmAddPronunciation
SmQueryPronunciations
SmRemovePronunciation
SmNaddPronunciationCallback
SmNqueryPronunciationCallback
SmNqueryPronunciationsCallback
SmNremovePronunciationCallback
IBM ViaVoice SDK for Windows
SmQueryPronunciations
SmQueryPronunciations
Purpose
SmQueryPronunciations queries a listing of added pronunciations.
This function provides a method for an application to request a list of word pronunciations for a
given spelling that have been added to the user's pronunciation pool within the buffer limits.
Syntax
int SmQueryPronunciations (SM_MSG *reply);
Parameters
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
SM_RC_SERVER_ERROR
SM_RC_SERVER_FILE_OPEN_ERROR
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Reply Structure Functions by Message Type
SM_QUERY_PRONUNCIATIONS_REPLY
SmGetPronunciations
SmGetRc
SmGetSpellings
Task Related Functions and Callbacks
SmAddPronunciation
SmQueryPronunciation
SmRemovePronunciation
SmNaddPronunciationCallback
SmNqueryPronunciationCallback
SmNqueryPronunciationsCallback
SmNremovePronunciationCallback
IBM ViaVoice SDK for Windows
SmQueryPronunciationsEx
SmQueryPronunciationsEx
Purpose
A new SMAPI function, SmQueryPronunciationsEx extends SmQueryPronunciations. This
function accepts an argument which specifies a starting point. It will return words beginning from
this starting point up to the limit SM_MAX_WORDS (500). If the specified starting point is
greater than the number of added words, no words will be returned.
Syntax
int SmQueryPronunciationsEx (unsigned long flags, unsigned long start,
SM_MSG *reply);
Parameters
flags
Reserved.
start
Specifies 0-origin starting place.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
SM_RC_SERVER_MALLOC_ERROR
Reply Structure Functions by Message Type
SM_QUERY_PRONUNCIATIONS_REPLY
SmGetSpellings
SmGetPronunciations
Task Related Functions and Callbacks
SmAddPronunciation
SmQueryPronunciation
SmRemovePronunciation
SmNaddPronunciationCallback
SmNqueryPronunciationCallback
SmNqueryPronunciationsCallback
SmNqueryPronunciationsExCallback
SmNremovePronunciationCallback
Remarks:
Calling SmQueryPronuciations is equivalent to calling SmQueryPronunciationsEx with a start
argument of 0.
If there are more added pronunciations than the limit SM_MAX_WORDS, this function may be
called repeatedly, specifying a start argument of 0 the first time and incrementing the start
argument by the number of pronunciations returned. When 0 pronunciations are returned, all
pronunciations have been retrieved.
Access Functions:
SmGetSpellings
SmGetPronunciations
IBM ViaVoice SDK for Windows
SmQueryScripts
SmQueryScripts
Purpose:
SmQueryScripts returns information about available scripts. The scripts about which information
is returned can be filtered by userid/enrollid, or task.
Syntax:
int SmQueryScripts (char *user_id, char *enrollid, char *task,
SM_MSG *reply );
Parameters:
user_id
Required if enrollid specified. Specifies user identifier.
enrollid
Required if user_id specified. Specifies enrollment identifier.
task
Optional: if not NULL specifies task for which data on associated scripts will be returned.
reply
SmAsynchronous or pointer to reply structure.
Remarks:
The Enroll stanza of the .eid file contains a Language tag. So specifying a userid/enrollid specifies
a language. Each .scr file contains a language tag in the script stanza. If a userid/enrollid pair is
specified SmQueryScripts will gather information about those scripts whose language tag
matches the language tag in the .eid file.
Filtering by task will be deferred for this first implementation.
The value of the name tag in the script stanza of the script files will be used to create the array of
script names returned.
The value of the description tag in the script stanza of the script files will be used to create the
array of descriptions returned.
The value of the type tag in the script stanza of the script files will be used to set the isolated/
continuous flag in the array of flags returned.
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
The value of the sentences tag in the script stanza of the script files will be used to create the array
of sizes returned.
The value of the increment tag in the script stanza of the script files will be used to create the array
of increments returned.
Access Functions:
SmGetDescriptions (Returns array of descriptions)
SmGetIncrements (Returns array of increments)
SmGetScriptFlags (Returns array of flags)
SmGetScripts (Returns array of script names)
SmGetSizes (Returns array of sizes)
SmGetStates (Returns array of statuses)
SmGetTasks (Returns array of task names)
SmGetTrained (Returns array of trained)
IBM ViaVoice SDK for Windows
SmQuerySessions
SmQuerySessions
Purpose
SmQuerySessions queries sessions and returns a list of connected recognition sessions.
Syntax
int SmQuerySessions (SM_MSG *reply);
Parameters
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_OK
Reply Structure Functions by Message Type
SM_QUERY_SESSIONS_REPLY
SmGetApplications
SmGetEnrollIds
SmGetRc
SmGetTasks
SmGetUserIds
Task Related Functions and Callbacks
SmDetachSessions
SmNdetachSessionsCallback
SmNquerySessionsCallback
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmQuerySpeechData
Purpose
SmQuerySpeechData queries the estimated size of speech data for the current session.
Syntax
int SmQuerySpeechData (SM_MSG *reply);
Parameters
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_OK
Reply Structure Functions by Message Type
SM_QUERY_SPEECH_DATA_REPLY
SmGetSpeechDataSize
IBM ViaVoice SDK for Windows
SmQueryTasks
SmQueryTasks
Purpose
SmQueryTasks queries a speech recognition engine domain list.
This function returns a list of the domains that can be used for dictation and enrollment. A domain
consists of a set of vocabularies, word-usage models, and other associated parameters used during
a recognition session. A domain name must be specified when the speech recognition engine is
initialized for a user.
Syntax
int SmQueryTasks (char *language, SM_MSG *reply);
Parameters
language
input - The language used for the domain. If specified as NULL, all domains are returned,
regardless of language.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
For synchronous call and callbacks:
SM_RC_SERVER_MALLOC_ERROR
Reply Structure Functions by Message Type
SM_QUERY_TASKS_REPLY
SmGetAlphabets
SmGetDescriptions
SmGetLanguages
SmGetRc
SmGetTasks
Task Related Functions and Callbacks
SmNqueryTasksCallback
IBM ViaVoice SDK for Windows
SmQueryTopics
SmQueryTopics
Purpose
SmQueryTopics will be called by a client application to request information about the current
topics or a specified topic. It accepts a taskid argument and will return information about only
those topics associated with that task.
Syntax
int SmQueryTasks (unsigned long flags, char *taskid, char *topic,
SM_MSG *reply);
Parameters
flags
Valid values: SM_INSTALLED_TOPICS, SM_ACTIVE_TOPICS
taskid
Name of task for which associated topics will be returned.
topic
Optional topic name
reply
The pointer to a reply structure or to SmAsynchronous indicating that the call is made
asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
For synchronous call and callbacks:
SM_RC_SERVER_MALLOC_ERROR
SM_RC_SERVER_FILE_OPEN_ERROR
Reply Structure Functions by Message Type
SM_QUERY_TOPICS_REPLY
SmGetDescriptions
SmGetSpellings
SmGetFlags
SmGetPreferred
Task Related Functions and Callbacks
SmQueryUserDefault
SmNqueryTopicsCallback
SmNqueryUserDefaultCallback
SmNsetUserDefaultCallback
Remarks:
If the flags value SM_INSTALLED_TOPIC is specified, information about all installed topics will
be returned. The topics will be returned in sorted order such that the topics which are designed to
be used the this task (for example, the preferred topics) will appear first. The npreferred field refers
to these topics. The entire array of topics is accessed using SmGetTopics. The npreferred field is
accessed using SmGetPreferred.
If the flags value SM_ACTIVE_TOPICS is specified, information about only the current active
topics will be returned.
Access Functions:
SmGetTopics (Returns array of topic names)
SmGetPreferred (Returns number of preferred)
SmGetDescriptions (Returns array of topic descriptions)
SmGetFlags (Returns flags)
IBM ViaVoice SDK for Windows
SmQueryUserDefault
SmQueryUserDefault
Purpose
The default enrollid, taskid, and topics are stored by the engine on a per-user basis. This new
function, SmQueryUserDefault is used to query one of these defaults for a particular user.
Syntax
int SmQueryUserDefault (char *user_id, long item, SM_MSG *reply);
Parameters
user_id
Specifies which default to query. Valid values:
SM_DEFAULT_ENROLLID
Specifies request for default enrollid.
SM_DEFAULT_TASK
Specifies a request for default task.
SM_DEFAULT_TOPICS
Specifies request for default topics.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
Reply Structure Functions by Message Type
SM_QUERY_USER_DEFAULT_REPLY
SmGetTask
SmGetTasks
SmGetUserId
SmGetUserIds
SmGetEnrollId
SmGetEnrollIds
SmGetDefaultTopics
Task Related Functions and Callbacks
SmConnect
SmOpen
SmSetUserDefault
SmNconnectCallback
SmNqueryUserDefaultCallback
SmNconnectCallback
SmNsetUserDefaultCallback
Remarks:
If the item SM_DEFAULT_TOPICS is specified, the item_value returned in the reply structure
will be a string of the default topics for the specified userid concatenated with blank delimiters (for
example, “topic1 topic2 topic3”).
Access Functions:
SmGetUserId (Returns userid for which default was queried.)
SmGetEnrollid(s) (Returns enrollid if requested item was
SM_DEFAULT_ENROLLID)
SmGetTask(s) (Returns task if requested item was SM_DEFAULT_TASK)
SmGetDefaultTopics (Returns topics if requested item was SM_DEFAULT_TOPICS)
IBM ViaVoice SDK for Windows
SmQueryUserInfo
SmQueryUserInfo
Purpose
SmQueryUserInfo queries user ID or enrollment ID information.
This function retrieves information associated with a user ID or an enrollment ID. Only one value
can be queried at a time.
Syntax
int SmQueryUserInfo (char *user_id, char *enroll_id, char *itemname,
SM_MSG *reply);
Parameters
user_id
input - The name of the user whose information is retrieved.
enroll_id
input - The enrollment ID of the user whose information is retrieved. This parameter is NULL if
information on the user ID is retrieved.
itemname
input - The queried item name. The special predefined itemname parameter,
SM_USER_DIRECTORY, returns the full path of the location where user files are stored. An
application can store its files in the same location.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_BAD_ENROLLID
SM_RC_BAD_ITEM
SM_RC_BAD_USERID
Reply Structure Functions by Message Type
SM_QUERY_USER_INFO_REPLY
SmGetEnrollId
SmGetEnrollIds
SmGetNameValue
SmGetRc
SmGetUserId
SmGetUserIds
Task Related Functions and Callbacks
SmQueryUsers
SmSetUserInfo
SmNqueryUsersCallback
SmNqueryUserInfoCallback
SmNsetUserInfoCallback
IBM ViaVoice SDK for Windows
SmQueryUsers
SmQueryUsers
Purpose
SmQueryUsers queries a user list.
This function returns a list of users allowed to use the speech recognition engine. To establish a
speech session, a user from this list must be supplied in the SmNuserId speech attribute.
Syntax
int SmQueryUsers (SM_MSG *reply);
Parameters
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_SERVER_MALLOC_ERROR
Reply Structure Functions by Message Type
SM_QUERY_USERS_REPLY
SmGetAlphabets
SmGetDescriptions
SmGetRc
SmGetUserIds
SmGetUsers
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Task Related Functions and Callbacks
SmQueryUserInfo
SmSetUserInfo
SmNqueryUsersCallback
SmNqueryUserInfoCallback
SmNsetUserInfoCallback
IBM ViaVoice SDK for Windows
SmQueryVocabs
SmQueryVocabs
Purpose
SmQueryVocabs queries currently defined vocabularies.
This function obtains the list of all defined speech recognition engine vocabularies that belong to
the current session. This includes predefined vocabularies and those defined after initialization
with the SmDefineVocab or SmDefineVocabEx function.
Syntax
int SmQueryVocabs (SM_MSG *reply);
Parameters
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Reply Structure Functions by Message Type
SM_QUERY_VOCABS_REPLY
SmGetRc
SmGetVocabList
Task Related Functions and Callbacks
SmAddToVocab
SmDefineVocab
SmDisableVocab
SmEnableVocab
SmQueryAddedWords
SmQueryEnabledVocabs
SmQueryWord
SmRemoveFromVocab
SmUndefineVocab
SmNaddToVocabCallback
SmNdefineVocabCallback
SmNdisableVocabCallback
SmNenableVocabCallback
SmNqueryAddedWordsCallback
SmNqueryEnabledVocabsCallback
SmNqueryVocabsCallback
SmNqueryWordsCallback
SmNremoveFromVocabCallback
SmNundefineVocabCallback
IBM ViaVoice SDK for Windows
SmQueryWord
SmQueryWord
Purpose
SmQueryWord checks for a specified word in all active vocabularies.
Syntax
int SmQueryWord (SM_WORD *word, SM_MSG *reply);
Parameters
word
input - The queried word.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_NOT_INVOCAB
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Reply Structure Functions by Message Type
SM_QUERY_WORD_REPLY
SmGetRc
SmGetVocabList
SmGetWords
Task Related Functions and Callbacks
SmAddToVocab
SmDefineVocab
SmDisableVocab
SmEnableVocab
SmPlayWords
SmQueryAddedWords
SmQueryEnabledVocabs
SmQueryVocabs
SmRemoveFromVocab
SmUndefineVocab
SmWordCorrection
SmNaddToVocabCallback
SmNdefineVocabCallback
SmNdisableVocabCallback
SmNenableVocabCallback
SmNplayWordsCallback
SmNplayWordsStatusCallback
SmNqueryAddedWordsCallback
SmNqueryEnabledVocabsCallback
SmNqueryVocabsCallback
SmNqueryWordsCallback
SmNremoveFromVocabCallback
SmNundefineVocabCallback
SmNwordCorrectionCallback
IBM ViaVoice SDK for Windows
SmReceiveMsg
SmReceiveMsg
Purpose
SmReceiveMsg receives a message from the speech recognition engine.
This function provides the method through which speech-aware Windows applications receive
asynchronous messages, including unsolicited asynchronous messages such as
SM_RECOGNIZED_TEXT, from the speech recognition engine. This function receives one
complete message from the speech recognition engine.
For details, see "Session Sharing" in the SMAPI Developer's Guide.
Syntax
int SmReceiveMsg (unsigned long ap_val, SM_MSG *msg);
Parameters
ap_val
input - For Windows applications, pass lParam here.
msg
output - The pointer to the reply structure.
Return Values
SM_RC_OK
SM_RC_REPLY_NULL
SM_RC_SM_NOT_OPEN
Reply Structure Functions by Message Type
SmGetRc
SmGetRcName
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmRecognizeNextWord
Purpose
SmRecognizeNextWord enables the recognition of the next word.
This function searches for the next word to decode. When running, the engine searches the
currently enabled vocabularies to find a word that matches the incoming speech. The vocabulary
that contains the best match determines what happens next:
.
If the matching word comes from a dictation vocabulary, the engine sends the firm and infirm
words to the application in an SM_RECOGNIZED_TEXT message and continues decoding.
.
If the matching word comes from a command vocabulary, the engine sends the word and some
alternative choices to the application in an SM_RECOGNIZED WORD message. The engine
then halts and waits for the application to request another word.
If a recognized word occurs in two or more vocabularies enabled at the same time, the engine
selects the word from the more recently enabled command vocabulary. Command vocabularies
always override dictation vocabularies; when a recognized word occurs in both a command and
dictation vocabulary enabled at the same time, the engine selects the command-vocabulary word.
Syntax
int SmRecognizeNextWord (SM_MSG *reply);
Parameters
reply
input/output -The pointer to the reply structure or to the SmAsynchronous value indicating that
the call is made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
IBM ViaVoice SDK for Windows
SmRecognizeNextWord
SM_RC_SM_NOT_OPEN
SM_RC_OK
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
Reply Structure Functions by Message Type
SM_RECOGNIZED_WORD
SmGetAlternates
SmGetFirmWords
SmGetRc
SmGetTimes
SM_RECOGNIZE_NEXT_WORD_REPLY
SmGetRc
For command vocabularies with microphone off and audio input stream processed:
SM_UTTERANCE_COMPLETED
SmGetRc
SmGetUtteranceNumber
Task Related Functions and Callbacks
SmHaltRecognizer
SmMicOff
SmMicOn
SmQuery
SmSet
SmNhaltRecognizerCallback
SmNmicOffCallback
SmNmicOnCallback
SmNqueryCallback
SmNrecognizeNextWordCallback
SmNrecognizedTextCallback
SmNrecognizedWordCallback
SmNsetCallback
SmNutteranceCompletedCallback
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmReleaseFocus
Purpose
SmReleaseFocus releases speech focus.
This function releases speech focus for the application calling this API. If the application does not
have the speech focus, this function returns SM_RC_NOT_VALID_REQUEST; otherwise it
returns SM_RC_OK.
If the call is made asynchronously the reply can be dispatched through either of the following:
. SM_RELEASE_FOCUS
. SmNreleaseFocusCallback
Syntax
int SmReleaseFocus (SM_MSG *reply);
Parameters
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_NOT_VALID_REQUEST
SM_RC_OK
Reply Structure Functions by Message Type
SM_RELEASE_FOCUS
SmGetRc
SM_FOCUS_LOST
Task Related Functions and Callbacks
SmRequestFocus
SmNfocusGrantedCallback
SmNfocusRequestedCallback
SmNreleaseFocusCallback
SmNrequestFocusCallback
IBM ViaVoice SDK for Windows
SmRemoveCallback
SmRemoveCallback
Purpose
SmRemoveCallback removes a single callback routine for a specific callback.
Syntax
int SmRemoveCallback (char *reply_name, SmHandler *handler,
caddr_t client_data);
Parameters
reply_name
input - The name of the type of message.
handler
input -The function name of the routine that handles the message.
client_data
input - The data passed back to the handler when it is called.
Return Values
SM_RC_ENOMEM
SM_RC_NOT_VALID_REQUEST
SM_RC_OK
SM_RC_SM_NOT_OPEN
Task Related Functions and Callbacks
SmAddCallback
SmDispatch
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmRemoveFromVocab
Purpose
SmRemoveFromVocab removes words from a dynamic vocabulary.
This function removes words previously added, using SmAddToVocab, to either dynamic
vocabularies created by SmDefineVocab or added to predefined vocabularies. This function can be
used to dynamically change command vocabularies in an application. Pronunciations for the
specified words are not removed by this call and can be reused later by words added to this or any
other vocabulary.
This call is valid only when the speech recognition engine is not accepting dictation.
Syntax
int SmRemoveFromVocab (char *vocab, short nvocwords,
SM_VOCWORD *vocwords[], SM_MSG *reply);
Parameters
vocab
input -The name of the vocabulary from which words are removed.
nvocwords
input - The number of words removed from the vocabulary. Limited to SM_MAX_VOCWORDS.
vocwords
input - The spellings of the words removed from the vocabulary.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
IBM ViaVoice SDK for Windows
SmRemoveFromVocab
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_BAD_VOCAB
SM_RC_NOT_VALID_REQUEST
SM_RC_SERVER_FILE_OPEN_ERROR
SM_RC_SERVER_FILE_WRITE_ERROR
Reply Structure Functions by Message Type
SM_REMOVE_FROM_VOCAB_REPLY
SmGetRc
SmGetVocabName
Task Related Functions and Callbacks
SmAddToVocab
SmDefineVocab
SmDisableVocab
SmEnableVocab
SmQueryAddedWords
SmQueryEnabledVocabs
SmQueryVocabs
SmQueryWord
SmUndefineVocab
SmNaddToVocabCallback
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmNdefineVocabCallback
SmNdisableVocabCallback
SmNenableVocabCallback
SmNqueryAddedWordsCallback
SmNqueryEnabledVocabsCallback
SmNqueryVocabsCallback
SmNqueryWordsCallback
SmNremoveFromVocabCallback
SmNundefineVocabCallback
IBM ViaVoice SDK for Windows
SmRemovePronunciation
SmRemovePronunciation
Purpose
SmRemovePronunciation removes a pronunciation from the user's personal pronunciation pool.
You cannot remove pronunciations from the permanent pool.
Syntax
int SmRemovePronunciation (char *spelling, char *pronunciation,
SM_MSG *reply);
Parameters
spelling
input - The word spelling which references the pronunciation.
pronunciation
input - The sounds-like spelling of the pronunciation to be removed.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
SM_RC_NOT_YET
SM_RC_SERVER_ERROR
Reply Structure Functions by Message Type
SM_REMOVE_PRONUNCIATION_REPLY
SmGetRc
SmGetSpelling
SmGetSpellings
Task Related Functions and Callbacks
SmAddPronunciation
SmCorrectText
SmCorrectTextCancel
SmNewContext
SmQueryPronunciation
SmQueryPronunciations
SmWordCorrection
SmNaddPronunciationCallback
SmNcorrectTextCallback
SmNcorrectTextCancelCallback
SmNnewContextCallback
SmNqueryPronunciationCallback
SmNqueryPronunciationsCallback
SmNremovePronunciationCallback
SmNwordCorrectionCallback
IBM ViaVoice SDK for Windows
SmRequestFocus
SmRequestFocus
Purpose
SmRequestFocus requests speech focus.
An application requests speech focus with a SmRequestFocus function call. If the call is made
asynchronously, the reply can be dispatched through either of the following:
SM_REQUEST_FOCUS
SmNrequestFocusCallback
If the request is accepted, an asynchronous message is sent after the engine grants focus. This
event can be dispatched through either of the following:
SM_FOCUS_GRANTED
SmNfocusGrantedCallback
Important notes on return code values include the following:
SM_RC_FOCUS_DENIED means the application with speech focus has grabbed the focus
and changes are blocked by the engine.
SM_RC_FOCUS_GRANTED means the requesting application had previously been granted
speech focus and no asynchronous notification message is generated by the engine.
Syntax
int SmRequestFocus (SM_MSG *reply);
Parameters
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_FOCUS_DENIED
SM_RC_FOCUS_GRANTED
SM_RC_OK
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Reply Structure Functions by Message Type
SM_REQUEST_FOCUS
SmGetRc
SM_FOCUS_GRANTED
Task Related Functions and Callbacks
SmReleaseFocus
SmNfocusGrantedCallback
SmNfocusRequestedCallback
SmNreleaseFocusCallback
SmNrequestFocusCallback
IBM ViaVoice SDK for Windows
SmRequestMicOff
SmRequestMicOff
Purpose
SmRequestMicOff requests that the microphone be turned off.
This function requests the speech recognition engine to request the application with speech focus
to turn off the microphone. If no application has speech focus, then SM_RC_NO_FOCUS_APP is
returned.
Syntax
int SmRequestMicOff (SM_MSG *reply);
Parameters
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_NO_FOCUS_APP
SM_RC_OK
Reply Structure Functions by Message Type
SM_REQUEST_MIC_OFF_REPLY
SmGetRc
SM_REQUEST_MIC_OFF
Task Related Functions and Callbacks
SmRequestMicOn
SmNrequestMicOffCallback
SmNrequestMicOnCallback
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmRequestMicOn
Purpose
SmRequestMicOn requests that the microphone be turned on.
This function requests the speech recognition engine to request the application with speech focus
to turn on the microphone. If no application has speech focus, then SM_RC_NO_FOCUS_APP is
returned.
Syntax
int SmRequestMicOn (SM_MSG *reply);
Parameters
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_NO_FOCUS_APP
SM_RC_OK
Reply Structure Functions by Message Type
SM_REQUEST_MIC_ON_REPLY
SmGetRc
SM_REQUEST_MIC_ON
Task Related Functions and Callbacks
SmRequestMicOff
SmNrequestMicOffCallback
SmNrequestMicOnCallback
IBM ViaVoice SDK for Windows
SmRestoreSpeechData
SmRestoreSpeechData
Purpose
SmRestoreSpeechData overwrites the current session files and resets the running utterance
number. Since this can take a long time, we suggest you call this asynchronously. Only valid in
recognition mode.
Note:
For this call to be valid, the application must first enable audio saving through
SmSet(SM_SAVE_AUDIO, TRUE). For more information on saving and restoring speech
sessions, reference “Writing ViaVoice Applications to Save and Restore Audio” in the SMAPI
Developer’s Guide.
Syntax
int SmRestoreSpeechData (char *archive, long version, SM_MSG *reply);
Parameters
archive
input - File name specified on SmSaveSpeechData.
version
input - Value defined by the application at save time and checked by the engine when the session is
restored.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_OK
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Reply Structure Functions by Message Type
SM_RESTORE_SPEECH_DATA_REPLY
SmGetSpeechDataArchive
SmGetSpeechDataSize
SmGetSpeechDataVersion
Task Related Functions and Callbacks
SmSaveSpeechData
IBM ViaVoice SDK for Windows
SmSaveSpeechData
SmSaveSpeechData
Purpose
SmSaveSpeechData saves current session speech data to a file. Since this can take a long time, we
suggest you call this asynchronously.
Note:
For this call to be valid, the application must first enable audio saving through
SmSet(SM_SAVE_AUDIO, TRUE). For more information on saving and restoring speech sessions,
reference “Writing ViaVoice Applications to Save and Restore Audio” in the SMAPI Developer’s
Guide.
Syntax
int SmSaveSpeechData (char *archive, long version, long flags,
SM_MSG *reply);
Parameters
archive
input - File name where data will be stored.
version
input - Identifies the data file.
flags
input - Identifies how the data should be saved, using one of the following values:
SM_NORMAL_FILE
The speech data is written to the file specified by the file name. This file will contain only
engine data.
SM_COMPOUND_FILE
The speech data is written to the Windows compound file specified by the file name, using
IStorage/IStream. The data is saved in a section named "VTDSessionArchive." This allows an
application to save both engine state and application state data in the same file.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Return Values
SM_RC_OK
Reply Structure Functions by Message Type
SM_SAVE_SPEECH_DATA_REPLY
SmGetSpeechDataArchive
SmGetSpeechDataOptions
SmGetSpeechDataSize
SmGetSpeechDataVersion
Task Related Functions and Callbacks
SmRestoreSpeechData
IBM ViaVoice SDK for Windows
SmSet
SmSet
Purpose
SmSet sets the value of a specified speech recognition engine parameter.
Syntax
int SmSet (short item, long value, SM_MSG *reply);
Parameters
item
input -The parameter set, which can be any one of the following:
SM_API_DEBUG
Values that can be set include the following: 0 is debugging off, 1 to 5 provide progressively
more debug information. A value of 1 or 2 provides flow of control information.
SM_API_DISPLAY
Reserved.
SM_API_LOG
The values are:
0=Off
1=Message headers
2=Message headers + content
3=Message headers + content + internal engine messages
Values above 3 are reserved.
SM_API_TIMING
Reserved.
SM_AUDIO_DEVICE
Selects the type of audio hardware.
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SM_AUDIO_CONFIGURATION
(Not applicable to Windows. Instead use Audio Setup program.)
Query the input source of the audio hardware where audio data is collected. The returned value
is bit mapped and can be any combination of the following values:
. SM_AUDIO_INPUT_MIC_HI_GAIN
. SM_AUDIO_INPUT_MIC_LO_GAIN
. SM_AUDIO_INPUT_LINE_LEFT
. SM_AUDIO_INPUT_LINE_RIGHT
. SM_AUDIO_INPUT_VARIABLE_GAIN
. SM_AUDIO_OUTPUT_LINE_LEFT
. SM_AUDIO_OUTPUT_LINE_RIGHT
. SM_AUDIO_OUTPUT_INTERNAL_SPEAKER
. SM_AUDIO_OUTPUT_VARIABLE_GAIN
Refer to the SMLIMITS.H file for bounds on input and output values.
SM_AUDIO_INPUT_MODE
(Not applicable to Windows. Instead use Audio Setup program.)
Sets the input source of the audio hardware where audio data is collected. Only one value can
be specified per call and values include the following:
. SM_AUDIO_INPUT_LINE_LEFT
. SM_AUDIO_INPUT_LINE_RIGHT
. SM_AUDIO_INPUT_MIC_HI_GAIN
. SM_AUDIO_INPUT_MIC_LO_GAIN
. SM_AUDIO_OUTPUT_MODE (Not applicable to Windows. Instead use the Audio Setup
program.)
If supported by the underlying audio, this parameter indicates the current output destination.
Only one value can be specified per call and values include the following:
. SM_AUDIO_OUTPUT_LINE_LEFT
. SM_AUDIO_OUTPUT_LINE_RIGHT
. SM_AUDIO_OUTPUT_INTERNAL_SPEAKER
IBM ViaVoice SDK for Windows
SmSet
.
SM_AUDIO_INPUT_GAIN (Not applicable to Windows. Instead use Audio Setup
program.)
.
If supported by underlying audio, this parameter allows you to set current gain setting.
Refer to the SMLIMITS.H file for bounds on input and output values.
SM_AUDIO_OUTPUT_GAIN
(Not applicable to Windows. Instead use Audio Setup program.)
If supported by underlying audio, this parameter allows you to set current gain setting. Refer to
the SMLIMITS.H file for bounds on input and output values. The IBM VoiceType Dictation
adapter does not support the value, SM_AUDIO_INPUT_LINE_RIGHT.
SM_AVAILABLE_AUDIO_DEVICES
For the default, SPCH_DEFAULT_SYSTEM_AUDIO. If using MWAVE,
SPCH_MWAVE_AUDIO.
SM_COMPLETE_COMMAND_TIMEOUT
These timeout parameters are used to control the behavior of finite state grammars. In
particular, they specify how much silence is needed at the end of commands before the engine
will make a recognition decision to accept or reject the command. The amount of silence
required to accept or reject a phrase that is unambiguously complete. Default value is 25
(csecs). Can be overridden by task dependent .par value.
SM_CONNECTION_ID
Sets the value of the WPARAM parameter for WM_CONTROL messages received from the
engine. If SM_PM_ENABLE is TRUE all asynchronous API messages from the engine are
WM_CONTROL messages. The WPARAM parameter is the value of the
SM_CONNECTION_ID.
SM_ENABLE_EXCLUSIVE_VOCABS
Sets the calling application's vocabularies. As part of the new global vocabulary mechanism,
applications have been given control of these as well as the navigator vocabularies. The SmSet
item SM_ENABLE_EXCLUSIVE_VOCABS now takes four values:
.
SM_EXCLUDE_NONE
.
SM_EXCLUDE_ALL
.
SM_EXCLUDE_GLOBALS
.
SM_EXCLUDE_ALLBUTNAVGLOBALS
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
The first two correspond to the old 0/1 values, so old clients will work as before. The third is
not very useful but would let a client hide any of these new globals. The fourth provides the
"super-global" function so that dictation clients can hide all vocabularies except those the
navigator defines as global.
SM_ENGINE_DEBUG
Reserved. Values that can be set include the following: 0 is disabled, greater than 0 provides
progressively more information.
SM_ENGINE_DISPLAY
Reserved. Values that can be set include the following: 0 is disabled, greater than 0 provides
progressively more information.
SM_ENGINE_LOG
Reserved. Values that can be set include the following: 0 is disabled, greater than 0 provides
progressively more information.
SM_IMMEDIATE_FIRMUP_MODE
This formerly unused item will now enable quick-firm-up mode, causing the engine to firm-up
the next command or short phrase terminated by silence. No infirm words are sent while it is
active and it is reset when the first firm word is sent.
Currently there are no new notifications, so the last 3 modes produce the same
SM_NOTIFY_FOCUS_APP_EXCLUSIVE engine state notification:
. SM_NOTIFY_NAVIGATOR_EXCLUSIVE
. SM_NOTIFY_FOCUS_APP_EXCLUSIVE
. SM_NOTIFY_NONE_EXCLUSIVE
SM_NOTIFY_AUDIO_LEVEL
Sets the returning of audio-level data during recognition or enrollment. The value is either
TRUE (1) or FALSE (0). See “SmGetAudioLevel” on page 200.
SM_NOTIFY_COMMAND_WORD
Sets whether the application is notified when a command word is recognized by having the
engine send a SM_COMMAND_WORD reply message. The value is either TRUE (1) or
FALSE (0).
SM_NOTIFY_ENGINE_STATE
Sets whether the application is notified of a speech recognition engine state change. The value
is either TRUE (1) or FALSE (0). See “SmGetEngineState” on page 205.
IBM ViaVoice SDK for Windows
SmSet
SM_NOTIFY_FOCUS_STATE
Sets whether the application is notified of a speech focus state change. The value is either
TRUE (1) or FALSE (0). See “SmGetFocusState” on page 216.
SM_NOTIFY_MIC_STATE
Sets whether the application is notified of a microphone state change. The value is either
TRUE (1) or FALSE (0). See “SmGetMicState” on page 221.
SM_OPTIMIZE_PERFORMANCE
Sets the speech recognition value for the engine depending on your requirements. Only one
value can be specified per call and values include the following:
. SM_OPTIMIZE_SPEED (fast)
. SM_OPTIMIZE_DEFAULT (balanced)
. SM_OPTIMIZE_ACCURACY (accurate)
SM_PARTIAL_COMMAND_TIMEOUT
These timeout parameters are used to control the behavior of finite state grammars. In
particular, they specify how much silence is needed at the end of commands before the engine
will make a recognition decision to accept or reject the command. The amount of silence
required to accept or reject a phrase that is both partially complete and complete. Default value
is 250 (csecs). It can be overridden by task dependent .par value.
For example, consider the grammar:
command = move up 3 move up five
Now consider the following acoustic scenarios:
1.MOVE
2.MOVE UP
3.MOVE UP FIVE
1.The engine will accept silences up to 0.5 seconds, waiting for the UP, before rejecting
the phrase as incomplete.
2.The engine will accept silences up to 0.5 seconds, waiting for the optional FIVE, before
accepting the phrase MOVE UP.
3.Then engine will wait only 0.1 seconds after the FIVE to accept the phrase.
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
For the example given, it seems that you would like to increase the
SM_PARTIAL_COMMAND_TIMEOUT in order to allow longer pauses within phrases.
Note that increasing this parameter will also increase the decision time for "ambiguously
complete" phrases.
SM_REDUCED_CPU_MODE
Sets the CPU mode of the speech recognition engine. The value is either TRUE (1) for reduced
CPU mode, or FALSE (0) for normal CPU mode. See “SmGetEngineState” on page 205.
SM_REJECTION_THRESHOLD
The speech recognition engine rejects out-of-vocabulary words or background noise during
monitored enrollment or command recognition. However, there is a trade-off between
correctly rejecting these words/noises, and incorrectly rejecting properly spoken words.
SM_REJECTION_THRESHOLD allows an application to adjust this trade-off. The limits for
the value of this parameter are SM_MIN_REJECTION_THRESHOLD and
SM_MAX_REJECTION_THRESHOLD, which are defined in SMLIMITS.H. At low settings
of SM_REJECTION_THRESHOLD, the engine allows more matches through with fewer
rejections. This causes more background noises or incorrect word matches to be recognized as
speech. Fewer correct words are rejected. At high rejection threshold values, the engine is
biased toward requiring a closer match, resulting in more rejections, and potentially more
rejections of correct words. This parameter also determines how close the match must be
between spoken acoustics and pronunciations in the SmAddPronunciation and
SmWordCorrection calls. See SMLIMITS.H for minimum and maximum limits.
SM_RELOAD_ACOUSTICS
This flag will be specified as an argument to the SmSet function. It will be used by a client
application to request that the engine reload acoustic data after speaker clustering or
microphone adaptation.
SM_SAVE_AUDIO
Enables the saving of speech data during recognition based on the following flags:
SM_SAVE_AUDIO_ADAPTATION -Saves audio data required for training.
SM_SAVE_AUDIO_ALTERNATES Saves audio data required for alternates
(SmQueryAlternates).
SM_SAVE_AUDIO_DEFAULT Saves all audio data for playback, add pronunciation and
alternates. DEFAULT is mapped to PLAYBACK|ALTERNATES|TRAINWORD to
preserve compatibility with older applications which asserted TRUE.
IBM ViaVoice SDK for Windows
SmSet
SM_SAVE_AUDIO_PLAYBACK - Saves audio data required for playback
(SmPlayWords)
SM_SAVE_AUDIO_PLAYBACKHIQ - Saves audio data required for high quality
playback.
SM_SAVE_AUDIO_TRAINWORD -Saves audio data required for trainword
(SmAddPronunciation).
SM_ENGINE_TIMING
Reserved
value
input - The value to set the parameter to.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_BAD_MODE
SM_RC_BAD_VALUE
SM_RC_NOT_YET
SM_RC_SERVER_FILE_OPEN_ERROR
SM_RC_SERVER_ERROR
SM_RC_EXISTS_IN_NOTIFY
SM_RC_NOT_IN_NOTIFY
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
Reply Structure Functions by Message Type
SM_SET_REPLY
SmGetRc
SmGetItemValue
For SM_NOTIFY_MIC_STATE parameter equal TRUE:
SM_MIC_STATE
SmGetMicState
SmGetRc
For SM_NOTIFY_FOCUS_STATE parameter equal TRUE:
SM_FOCUS_STATE
SmGetApplication
SmGetFocusState
SmGetRc
For SM_NOTIFY_ENGINE_STATE parameter equal TRUE:
SM_ENGINE_STATE
SmGetEngineState
SmGetRc
For SM_NOTIFY_COMMAND_WORD parameter equal TRUE:
SM_COMMAND_WORD
SmGetApplication
SmGetFirmWords
SmGetRc
For SM_NOTIFY_AUDIO_LEVEL parameter equal TRUE:
SM_AUDIO_LEVEL
SmGetAudioLevel
SmGetRc
IBM ViaVoice SDK for Windows
SmSet
Task Related Functions and Callbacks
SmHaltRecognizer
SmMicOff
SmMicOn
SmQuery
SmRecognizeNextWord
SmNhaltRecognizerCallback
SmNmicOffCallback
SmNmicOnCallback
SmNqueryCallback
SmNrecognizeNextWordCallback
SmNrecognizedTextCallback
SmNrecognizedWordCallback
SmNsetCallback
SmNutteranceCompletedCallback
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmSetArg
Purpose
SmSetArg is a macro that fills an SmArg structure when given its components.
This function sets the components of the arg parameter. The pointer to arg or to a list of similarly
created arguments can then be passed to a number of functions, such as SmOpen and SmConnect.
For further information on attributes, reference “SMAPI Attributes” on page 305. Also, see
"Establishing a Speech Session" in the SMAPI Developer's Guide.
Syntax
void SmSetArg (SmArg arg, char *name, long value);
Parameters
arg
input - The argument.
name
input -The name of the attribute.
value
input - The value of the attribute.
Return Values
None
Task Related Functions and Callbacks
SmConnect
SmOpen
SmNconnectCallback
IBM ViaVoice SDK for Windows
SmSetBinary
SmSetBinary
Purpose
SmSetBinary sets the value of a specified speech recognition engine parameter.
This function is used instead of SmSet to set values of arbitrary length and data type.
Syntax
int SmSetBinary (short item, short length, void *value, SM_MSG *reply);
Parameters
item
input -The parameter to be set, which can be any of the following:
SM_AUDIO_SOURCE -Specifies setting value in audio library.
SM_MNR_VALUE - Specifies setting mnr value.
length
input - The length in bytes of the data pointed to by the argument value.
value
input - Points to data to which item is to be set.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
If item is SM_AUDIO_SOURCE return values depend on audio library implementation of
AudioSetSource.
If item is SM_MNR_VALUE return value is SM_RC_OK.
Reply Structure Functions by Message Type
SM_SET_BINARY_REPLY
SmGetRc
SmGetBinaryItemValue
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Task Related Functions and Callbacks
SmQueryBinary
SmNsetBinaryCallback
IBM ViaVoice SDK for Windows
SmSetDefault
SmSetDefault
Purpose
SmSetDefault sets a default value for a user, enrollment, task ID speech attribute, or the default
topics. The default user, enrollment, or task ID is used by the speech recognition engine when
SM_USE_DEFAULT is specified for the speech attribute as arguments when calling SmOpen and
SmConnect. The default topics are always used by the speech recognition engine.
Syntax
int SmSetDefault (long item, char *item_value, SM_MSG *reply);
Parameters
item
input -Type of default ID speech attribute. Valid values include the following:
SM_DEFAULT_USERID
SM_DEFAULT_ENROLLID
SM_DEFAULT_TASK
SM_DEFAULT_TOPICS
item_value
input -Value for default ID speech attribute.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_OK
Reply Structure Functions by Message Type
SM_SET_DEFAULT_REPLY
SmGetRc
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Task Related Functions and Callbacks
SmConnect
SmOpen
SmQueryDefault
SmQueryUserDefault
SmSetUserDefault
SmNqueryDefaultCallback
SmNqueryUserDefaultCallback
SmNsetDefaultCallback
SmNsetUserDefaultCallback
Remarks:
The default enrollid, taskid, and topics are stored on a per-user basis. SmSetDefault called with an
item value of SM_DEFAULT_USERID will set the value of the default userid. SmSetDefault
called with other item values will set the default enrollid, taskid or topics for the default userid. To
set the default enrollid, task or topics for a user other than the default user, the function
SmSetUserDefault is provided.
IBM ViaVoice SDK for Windows
SmSetDirectory
SmSetDirectory
Purpose
SmSetDirectory sets the name of files or directories used by the engine.
In this release, SmSetDirectory defines the output.wav file name, used when SmPlayWords is
subsequently called with the SM_PLAY_WORDS_SAVE_WAVFILE option flag asserted. The
fully qualified file name is passed in the directory_name string.
Syntax
int SmSetDirectory(short *file_class, char *directory_name, SM_MSG *reply);
Parameters
file_class
input - Indicates type of file name being set (Reserved for future use)
directory_name
input - String containing the file/directory name being set.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_OK
SM_RC_BAD_VALUE (if file name is not valid)
Reply Structure Functions by Message Type
SM_SET_DEFAULT_REPLY
SmGetRc
Task Related Functions and Callbacks
SmConnect
SmOpen
SmQueryDefault
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmSetUserDefault
Purpose
SmSetUserDefault is a new function. The default enrollid, task id, and topics will be used to set
one of these defaults at a time for a particular user.
Syntax
int SmSetUserDefault (char *user_id, long item, char *item_value,
SM_MSG *reply);
Parameters
user_id
Userid for which default is set.
item
Specifies which default is set. Valid values:
SM_DEFAULT_ENROLLID
Specifies setting default enrollid
SM_DEFAULT_TASK
Specifies setting default task
SM_DEFAULT_TOPICS
Specifies setting default topics.
itemvalue
New default value to set.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
IBM ViaVoice SDK for Windows
SmSetUserDefault
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
SM_RC_SERVER_FILE_OPEN_ERROR
Reply Structure Functions by Message Type
SM_SET_USER_DEFAULT_REPLY
Task Related Functions and Callbacks
SmConnect
SmOpen
SmQueryUserDefault
SmNconnectCallback
SmNqueryUserDefaultCallback
SmNconnectCallback
SmNsetUserDefaultCallback
Remarks:
If the item SM_DEFAULT_TOPICS is specified, the item_value argument must be a string of the
default topics for the specified userid concatenated with blank delimiters (for example, “topic1
topic2 topic3”).
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmSetUserInfo
Purpose
SmSetUserInfo sets user information.
This function stores any information that pertains to a user ID or an enrollment ID. It is the
responsibility of the speech-aware application to select a proper item name (tag) that uniquely
identifies stored information. This item is used later by the SmQueryUserInfo function for
retrieving the stored information. This function allows an application to associate string
information with a particular user ID or enrollment ID.
Syntax
int SmSetUserInfo (char *user_id, char *enroll_id, char *itemname,
char *itemvalue, SM_MSG *reply);
Parameters
user_id
input - The name of the user whose information is stored.
enroll_id
input - The enrollment ID of the user whose information is to be stored. This parameter is NULL if
the information stored is related to the user ID.
itemname
input -The name of the information item to be stored.
itemvalue
input - The value of the information item to be stored.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
IBM ViaVoice SDK for Windows
SmSetUserInfo
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_BAD_ENROLLID
SM_RC_BAD_ITEM
SM_RC_BAD_USERID
Reply Structure Functions by Message Type
SM_SET_USER_INFO_REPLY
SmGetEnrollId
SmGetEnrollIds
SmGetRc
SmGetUserId
SmGetUserIds
Task Related Functions and Callbacks
SmQueryUserInfo
SmQueryUsers
SmNqueryUsersCallback
SmNqueryUserInfoCallback
SmNsetUserInfoCallback
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmUndefineVocab
Purpose
SmUndefineVocab deletes a dynamic vocabulary.
This function deletes a vocabulary defined by a call to SmDefineVocab or SmDefineVocabEx.
After the vocabulary is deleted, no calls to SmEnableVocab, SmDisableVocab, SmAddToVocab,
or SmRemoveFromVocab can be made for the specified vocabulary. The specified vocabulary
must be disabled to be deleted.
SmUndefineVocab releases the image of the private area of the FSG file. SmUndefineVocab is
valid only when the speech recognition engine is not decoding speech to text. See "Setting Up
Vocabularies" in the SMAPI Developer's Guide for examples of conditions when the engine is not
decoding speech to text.
Syntax
int SmUndefineVocab (char *vocab, SM_MSG *reply);
Parameters
vocab
input - The name of the vocabulary undefined.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
Return Values
SM_RC_BAD_VOCAB
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_SM_NOT_OPEN
IBM ViaVoice SDK for Windows
SmUndefineVocab
SM_RC_OK
SM_RC_INVALID_PARM_MAX_LEN
For synchronous call and callbacks:
SM_RC_NOT_VALID_REQUEST
Reply Structure Functions by Message Type
SM_UNDEFINE_VOCAB_REPLY
SmGetRc
SmGetVocabName
Task Related Functions and Callbacks
SmAddToVocab
SmDefineVocab
SmDisableVocab
SmEnableVocab
SmQueryAddedWords
SmQueryEnabledVocabs
SmQueryVocabs
SmQueryWord
SmRemoveFromVocab
SmNaddToVocabCallback
SmNdefineVocabCallback
SmNdisableVocabCallback
SmNenableVocabCallback
SmNqueryAddedWordsCallback
SmNqueryEnabledVocabsCallback
SmNqueryVocabsCallback
SmNqueryWordsCallback
SmNremoveFromVocabCallback
SmNundefineVocabCallback
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
SmWordCorrection
Purpose
SmWordCorrection corrects a misrecognized word.
This function notifies the speech recognition engine that an incorrectly recognized word or
sequence of words was corrected by the user.
The user corrects the word by providing the correct spelling. This call specifies whether the
pronunciation for this word is to be added to the user's personal pronunciation pool and whether
the corrected spelling is to be added to the user's personal text vocabulary extension. The speech
recognition engine uses this information to assist future recognition.
If an SmWordCorrection call fails and the call is immediately repeated with exactly the same
parameters, the engine will automatically apply more lenient threshold parameters the second time
(reference “SmSet” on page 167 for a detailed description of the
SM_REJECTION_THRESHOLD parameter).
This call is valid only when the speech recognition engine is not decoding speech to text. See
"Changing the Engine Decoding State" in the SMAPI Developer's Guide for examples of
conditions when the engine is not decoding speech to text.
Notes:
-For this call to be valid, the application must first enable audio saving through
SmSet(SM_SAVE_AUDIO, TRUE). For more information on saving and restoring speech
sessions, reference “Writing ViaVoice Applications to Save and Restore Audio” in the SMAPI
Developer’s Guide.
-If you get an RC_OK return value for a synchronous call, you need to check the status by
performing an SmGetStatus function.
Syntax
int SmWordCorrection (short ntags, long tags[], short nspells,
char *spellings[], char *pronunciations[], short new_pronunciation,
SM_MSG *reply);
Parameters
ntags
input - The number of tagged words corrected.
IBM ViaVoice SDK for Windows
SmWordCorrection
tags
input - An array of tags for the words corrected.
nspells
input -The number of new words to replace the words in error.
spellings
input - An array of new spellings for the words corrected.
pronunciations
input -An array of spoken-like spellings for the words that were corrected if their pronunciation is
different than the spellings would suggest. Specify NULL if the spoken-like spelling is the same as
the true spelling.
new_pronunciation
input -A flag to indicate whether the corrected word is a new pronunciation for a word already in
the recognition vocabulary. The following flag values are valid:
SM_CHECK_SPELLING
Check the spelling of the new word before adding it to the recognition vocabulary as a new
word. SM_CHECK_SPELLING is valid only with SM_DEFAULT_ADDWORD.
SM_FORCE_ADDWORD and SM_REPLACE_ADDWORD override the spelling check.
SM_FORCE_ADDWORD
The corrected word is a new pronunciation and needs to be added as a new word even if the
word already exists in the vocabulary.
SM_NO_ADDWORD
The corrected word need not be added to the recognition vocabulary as a new word.
SM_DEFAULT_ADDWORD
The user needs to decide whether to add the corrected word to the recognition vocabulary. The
speech recognition engine produces a pronunciation if one does not already exist.
SM_REPLACE_ADDWORD
The new pronunciation needs to replace any existing pronunciations of the corrected word.
reply
input/output -The pointer to a reply structure or to SmAsynchronous indicating that the call is
made asynchronously.
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
Return Values
SM_RC_DEALLOCATING_SH_MEM
SM_RC_EALLOC
SM_RC_EBADHANDLE
SM_RC_ENOCONN
SM_RC_ENOMEM
SM_RC_ENOMSG
SM_RC_ENOSERVER
SM_RC_EUNEXP
SM_RC_INVALID_PARM_MAX_LEN
SM_RC_OK
SM_RC_RECORDING_REQUIRED
SM_RC_SM_NOT_OPEN
For synchronous call and callbacks:
SM_RC_MULTIPLE_SPELLINGS
SM_RC_NOT_VALID_REQUEST
SM_RC_RECORDING_REQUIRED
Reply Structure Functions by Message Type
SM_WORD_CORRECTION_REPLY
SmGetPronunciations
SmGetRc
SmGetSpellings
SmGetStatus
SmGetTags
Task Related Functions and Callbacks
SmCorrectText
SmCorrectTextCancel
SmNewContext
SmNcorrectTextCallback
SmNcorrectTextCancelCallback
SmNnewContextCallback
SmNplayWordsCallback
IBM ViaVoice SDK for Windows
SmWordCorrection
SmNplayWordsStatusCallback
SmNqueryAddedWordsCallback
SmNqueryWordsCallback
SmNremovePronunciationCallback
SmNwordCorrectionCallback
SmPlayWords
SmQueryAddedWords
SmQueryWord
SmRemovePronunciation
IBM SMAPI Reference
Function Calls to the Speech Recognition Engine
IBM ViaVoice SDK for Windows
Chapter 4 Data Access Functions
This chapter lists and describes the function calls that retrieve data from reply messages. These
function calls do not interact with the engine; they provide local access to the logical contents of a
message that has already been received.
SmGetAlphabets
Purpose
SmGetAlphabets retrieves a list of alphabets related to specific enroll IDs or tasks.
SmGetAlphabets retrieves a list of alphabet strings. This function can extract data from the
following reply message structures:
. SM_QUERY_ENROLLIDS_REPLY
. SM_QUERY_TASKS_REPLY
The alphabet identifies the base technology used in the engine. Enrollment data must match engine
technology. The current engine is using a ranks based technology (alphabet="R".). The previous
engine used a Z-label based technology (alphabet="Z".).
Syntax
int SmGetAlphabets (SM_MSG reply, unsigned long *nalphabets,
char ***alphabets);
Parameters
reply
input - The reply structure from a SMAPI function.
nalphabets
output - The pointer to the number of alphabets.
alphabets
output - The pointer to a list of alphabets.
IBM SMAPI Reference
Data Access Functions
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Task Related Functions and Callbacks
SmQueryEnrollIds
SmQueryTasks
IBM ViaVoice SDK for Windows
SmGetAlternates
SmGetAlternates
Purpose
SmGetAlternates retrieves alternative words.
SmGetAlternates retrieves the list of alternative words from the reply message. This function can
extract data from the following reply message structures:
. SM_QUERY_ALTERNATES_REPLY
. SM_RECOGNIZED_WORD
Syntax
int SmGetAlternates (SM_MSG reply, unsigned long *nwords, SM_WORD **words);
Parameters
reply
input - The reply structure from a SMAPI function.
nwords
output - The pointer to the number of alternative words.
words
output -The pointer to a list of alternative words.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure Functions by Message Type
SmQueryAlternates
IBM SMAPI Reference
Data Access Functions
SmGetAnnotations
Purpose
SmGetAnnotations retrieves annotations.
SmGetAnnotations extracts the base vocabulary name from the reply message, uses this name to
access the image of the private area of the FSG file, and uses the offsets stored in SM_WORD to
access the annotation data. This function can extract data from the following reply message
structures:
. SM_RECOGNIZED_PHRASE
. SM_QUERY_PHRASE_ALTERNATIVES_REPLY
Annotations are stored in an SM_ANNOTATION structure. SmGetAnnotations returns a pointer
to this structure. SM_ANNOTATION is defined as:
struct _SM_ANNOTATION (
long type; // Type of annotation
union
{
long numeric; // Return numeric annotations
char *string; // Return string annotations
void *other; // Reserved
} annodata;
);
Types of annotations are defined as :
. SM_ANNOTATION_NONE
. SM_ANNOTATION_NUMERIC
. SM_ANNOTATION_STRING
. SM_ANNOTATION_OTHER (Reserved)
The SM_ANNOTATION structure has a one-to-one correspondence with the corresponding
SM_WORD structure. Lack of an annotation on a particular word is indicated by an annotation of
type SM_ANNOTATION_NONE.
IBM ViaVoice SDK for Windows
SmGetAnnotations
Syntax
int SmGetAnnotations (SM_MSG reply, unsigned long *nwords,
SM_ANNOTATION **annotations);
Parameters
reply
input - The reply structure from a SMAPI function.
nwords
output - The pointer to the number of annotations.
annotations
output - The pointer to an annotation structure.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_SERVER_FILE_READ_ERROR
Reply Structure Functions by Message Type
SmDefineGrammar
SmUndefineVocab
IBM SMAPI Reference
Data Access Functions
SmGetApplication
Purpose
SmGetApplication retrieves the name of the application.
SmGetApplication extracts the application name from the following reply messages:
. SM_COMMAND_WORD
. SM_FOCUS_STATE
Syntax
int SmGetApplication (SM_MSG reply, char **application);
Parameters
reply
input - The reply structure from a SMAPI function.
application
output - The pointer to the name of the application.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure
SmNcommandWordCallback
SmNfocusStateCallback
IBM ViaVoice SDK for Windows
SmGetApplications
SmGetApplications
Purpose
SmGetApplications retrieves the names of the applications that have established a session.
SmGetApplications extracts the application names from the SM_QUERY_SESSIONS_REPLY
reply message sent by the speech recognition engine to the application.
Syntax
int SmGetApplications (SM_MSG reply, unsigned long *nsessions,
char ***reco_sessions);
Parameters
reply
input - The reply structure from a SMAPI function.
nsessions
output - A pointer to the number of sessions that have been established with the speech recognition
engine.
reco_sessions
output - A pointer to a list of applications that have established sessions with the speech
recognition engine.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure Functions by Message Type
SmNquerySessionsCallback
IBM SMAPI Reference
Data Access Functions
SmGetAudioLevel
Purpose
SmGetAudioLevel retrieves the level of the audio signal during recognition.
SmGetAudioLevel provides information about the level of audio received by the speech
recognition engine when the microphone is on. If previously requested by the
SM_AUDIO_INPUT_LEVEL parameter supplied to the SmSet function, packets of audio level
values are periodically sent to the speech recognition engine, which in turn calls
SmNaudioLevelCallback and/or sends a message to your window procedure. Audio-level
information can then be obtained using this function. Audio-level values range from
0(SM_MIN_AUDIO_LEVEL) to 10(SM_MAX_AUDIO_LEVEL) with acceptable volume
ranges from 2 to 7. The average rate sent by the engine is 5 audio-level values per second. This
function can extract data from the following reply message structures:
. SM_AUDIO_LEVEL
Syntax
int SmGetAudioLevel (SM_MSG reply, short *volume);
Parameters
reply
input - The reply structure from a SMAPI function.
volume
output - The pointer to a short. Volume can range from SM_MIN_AUDIO_LEVEL to
SM_MAX_AUDIO_LEVEL inclusive.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmNaudioLevelCallback
IBM ViaVoice SDK for Windows
SmGetBinaryItemValue
SmGetBinaryItemValue
Purpose
SmGetBinaryItemValue retrieves the value of item of arbitrary length and data type.
SmGetBinaryItemValue can extract data from the following reply message structures:
. SM_SET_BINARY_REPLY
. SM_QUERY_BINARY_REPLY
Syntax
int SmGetBinaryItemValue (SM_MSG sm_reply, unsigned long *item,
unsigned long *length, void ***value);
Parameters
sm_reply
input - The reply structure from a SMAPI function.
item
output - A pointer to the name of the item.
length
output - A pointer to the length of the data pointed by the value argument.
value
output -A pointer to the value of the item.
Return Values
SM_RC_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure Functions by Message Type
SmSetBinary
SmQueryBinary
IBM SMAPI Reference
Data Access Functions
SmGetCodePage
Purpose
SmGetCodepage returns the Windows codepage used for character strings in/out of the engine.
SmGetCodepage can extract data from the following reply message structures:
. SM_CONNECT_REPLY (Recognition Mode Only)
Syntax
int SmGetCodepage (SM_MSG reply, unsigned long *codepage);
Parameters
reply
input - The reply structure from a SMAPI function.
codepage
output -Returns the Windows codepage used for character strings in/out of the engine.
Return Values
SM_RC_OK
SM_RC_REPLY_NULL
SM_RC_SM_EINVAL_MSG_TYPE
IBM ViaVoice SDK for Windows
SmGetDescriptions
SmGetDescriptions
Purpose
SmGetDescriptions retrieves a list of enrollment enroll IDs, scripts, tasks, or users.
SmGetDescriptions can extract data from the following reply message structures:
. SM_QUERY_ENROLLIDS_REPLY
. SM_QUERY_SCRIPTS_REPLY SM_QUERY_TASKS_REPLY
. SM_QUERY_USERS_REPLY
. SM_QUERY_LANGUAGES_REPLY
. SM_QUERY_TOPICS_REPLY
Syntax
int SmGetDescriptions (SM_MSG reply, unsigned long *ndescriptions,
char ***descriptions);
Parameters
reply
input - The reply structure from a SMAPI function.
ndescriptions
output -The pointer to the number of descriptions.
descriptions
output - The pointer to a list of descriptions.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
IBM SMAPI Reference
Data Access Functions
Reply Structure Functions by Message Type
SmQueryEnrollIds
SmQueryLanguages
SmQueryTasks
SmQueryUsers
IBM ViaVoice SDK for Windows
SmGetEngineState
SmGetEngineState
Purpose
SmGetEngineState retrieves the engine state.
SmGetEngineState extracts the engine state from an SM_ENGINE_STATE reply message sent
by the speech recognition engine to an application. SM_ENGINE_STATE reply messages are
controlled by the SM_NOTIFY_ENGINE_STATE parameter of the SmSet function.
Syntax
int SmGetEngineState (SM_MSG reply, unsigned long *engine_state);
Parameters
reply
input - The reply structure from a SMAPI function.
engine_state
output - The pointer to an unsigned long. Values include the following:
. SM_NOTIFY_NORMAL_CPU
. SM_NOTIFY_REDUCED_CPU
. SM_NOTIFY_ENGINE_BUSY
. SM_NOTIFY_ENGINE_IDLE
. SM_NOTIFY_NAVIGATOR_EXCLUSIVE
. SM_NOTIFY_FOCUS_APP_EXCLUSIVE
. SM_NOTIFY_NONE_EXCLUSIVE
. SM_NOTIFY_RECOGNIZED_SPEECH
. SM_NOTIFY_SPEECH_START
. SM_NOTIFY_SPEECH_STOP
. SM_NOTIFY_SPEECH_TOO_HIGH
. SM_NOTIFY_SPEECH_TOO_LOW
. SM_NOTIFY_PRONUNCIATIONS_ADDED
IBM SMAPI Reference
Data Access Functions
. SM_NOTIFY_PRONUNCIATIONS_DELETED
. SM_NOTIFY_ENGINE_SETTINGS_CHANGED for the following parameters:
. SM_REJECTION_THRESHOLD
. SM_AUDIO_CONFIGURATION
. SM_AUDIO_DEVICE
. SM_AUDIO_INPUT_GAIN
. SM_AUDIO_INPUT_MODE
. SM_AUDIO_OUTPUT_GAIN
. SM_AUDIO_OUTPUT_MODE
. SM_NOTIFY_APPLICATION_CONNECTED
. SM_NOTIFY_APPLICATION_DISCONNECTED
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure Functions by Message Type
SmNengineStateCallback
IBM ViaVoice SDK for Windows
SmGetEnrollId
SmGetEnrollId
Purpose
SmGetEnrollId retrieves an enrollment ID.
SmGetEnrollId is valid only for reply message structures that contain one enrollment ID. Use
SmGetEnrollIds for reply message structures with multiple enrollment IDs. SmGetEnrollId can
extract data from the following reply message structures:
. SM_CONNECT_REPLY
. SM_QUERY_DEFAULT_REPLY
. SM_QUERY_USER_DEFAULT_REPLY
. SM_QUERY_USER_INFO_REPLY
. SM_SET_USER_INFO_REPLY
Syntax
int SmGetEnrollId (SM_MSG reply, char **enroll_id);
Parameters
reply
input - The reply structure from a SMAPI function.
enroll_id
output - The pointer to an enrollment ID.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure Functions by Message Type
SmQueryDefault
SmQueryEnrollIds
SmQueryUserInfo
SmSetUserInfo
IBM SMAPI Reference
Data Access Functions
SmGetEnrollIds
Purpose
SmGetEnrollIds retrieves a list of enrollment IDs.
SmGetEnrollIds extracts data from the following reply message structures:
. SM_QUERY_DEFAULT_REPLY
. SM_QUERY_SESSIONS_REPLY
. SM_CONNECT_REPLY
. SM_QUERY_ENROLLIDS_REPLY
. SM_QUERY_USER_DEFAULT_REPLY
. SM_QUERY_USER_INFO_REPLY
. SM_SET_USER_INFO_REPLY
Syntax
int SmGetEnrollIds (SM_MSG reply, unsigned long *nenroll_ids,
char ***enroll_ids);
Parameters
reply
input - The reply structure from a SMAPI function.
nenroll_ids
output -The pointer to the number of enrollment IDs.
enroll_ids
output - The pointer to a list of enrollment IDs.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
IBM ViaVoice SDK for Windows
SmGetEnrollIds
Reply Structure Functions by Message Type
SmQueryEnrollIds
SmQueryUserInfo
SmSetUserInfo
IBM SMAPI Reference
Data Access Functions
SmGetEventId
Purpose
SmGetEventId retrieves the event ID.
SmGetEventId can extract data from the following reply message structures:
. SM_EVENT_NOTIFY_REPLY
. SM_EVENT_SYNCH
Syntax
int SmGetEventId (SM_MSG reply, unsigned long *event_id);
Parameters
reply
input - The reply structure from a SMAPI function.
event_id
output - The pointer to the event ID.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure Functions by Message Type
SmEventNotify
SmNeventSynchCallback
IBM ViaVoice SDK for Windows
SmGetEventOptions
SmGetEventOptions
Purpose
SmGetEventOptions retrieves options for an event.
SmGetEventOptions can extract data from the following reply message structure:
. SM_EVENT_SYNCH
Syntax
int SmGetEventOptions (SM_MSG reply, unsigned long *options);
Parameters
reply
input - The reply structure from a SMAPI function.
options
output - The pointer to options.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure Functions by Message Type
SmNeventSynchCallback
IBM SMAPI Reference
Data Access Functions
SmGetFirmWords
Purpose
SmGetFirmWords retrieves firm words.
SmGetFirmWords extracts the SM_WORD from the following reply message structures:
. SM_RECOGNIZED_PHRASE
. SM_RECOGNIZED_TEXT
. SM_RECOGNIZED_WORD
. SM_COMMAND_WORD
. SM_QUERY_PHRASE_ALTERNATIVES_REPLY
Syntax
int SmGetFirmWords (SM_MSG reply, unsigned long *nwords, SM_WORD **words);
Parameters
reply
input - The reply structure from a SMAPI function.
nwords
output -The pointer to the number of firm words.
words
output - The pointer to a list of firm words.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure Functions by Message Type
SmNrecognizedTextCallback
SmNrecognizedWordCallback
SmNcommandWordCallback
IBM ViaVoice SDK for Windows
SmGetFlags
SmGetFlags
Purpose
SmGetFlags is used to retrieve a single flags field from a reply structure. It is valid only for the
following message types:
. SM_AUTO_COMPLETE_REPLY
. SM_CONNECT_REPLY
. SM_DISCARD_SPEECH_DATA_REPLY
. SM_QUERY_PHRASE_ALTERNATIVES_REPLY
. SM_QUERY_PRONUNCIATIONS_REPLY
. SM_QUERY_TOPICS
. SM_QUERY_TASKS_REPLY
Syntax
int SmGetFlags (SM_MSG reply, unsigned long *flags);
Parameters
reply
input - The reply structure from a SMAPI function.
flags
output - Receives flags field.
Return Values
SM_RC_OK
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryPhraseAlternatives
SmConnect
IBM SMAPI Reference
Data Access Functions
Related Functions:
SmAutoComplete
SmDiscardSpeechData
SmQuerAddedWordsEx
SmQuerPhraseAlternatives
SmQueryPronunciationsEx
SmQueryTopics
IBM ViaVoice SDK for Windows
SmGetFocusChangeReason
SmGetFocusChangeReason
Purpose
SmGetFocusChangeReason returns a reason code on focus changes.
SmGetFocusChangeReason extracts the reason from the SM_FOCUS_STATE reply structure.
The change reason is only available when the focus state notification is for
SM_NOTIFY_FOCUS_RELEASED.
The "change reason" flags can be:
.
SM_NOTIFY_FOCUS_CHANGE_ON_RELEASE (The application released the focus, by
itself)
.
SM_NOTIFY_FOCUS_CHANGE_ON_REQUEST (The application released focus due to
request)
Syntax
int SmGetFocusChangeReason (SM_MSG reply, unsigned long *reason);
Parameters
reply
input - The reply structure from a SMAPI function.
reason
output - The pointer to the reason change.
Return Values
SM_RC_OK
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmGetFocusState
SmNFocusStateCallback
IBM SMAPI Reference
Data Access Functions
SmGetFocusState
Purpose
SmGetFocusState retrieves the focus state.
SmGetFocusState extracts the focus state from the SM_FOCUS_STATE reply message sent by
the speech recognition engine to an application. SM_FOCUS_STATE reply messages are
controlled by the SmSet SM_NOTIFY_FOCUS_STATE parameter. The name of the application
causing the focus change can be extracted from SM_FOCUS_STATE with SmGetApplication.
Syntax
int SmGetFocusState (SM_MSG reply, unsigned long *focus_state);
Parameters
reply
input - The reply structure from an API function.
focus_state
output - The pointer to an unsigned long. Values include the following:
. SM_NOTIFY_FOCUS_REQUESTED
. SM_NOTIFY_FOCUS_GRANTED
. SM_NOTIFY_FOCUS_DENIED
. SM_NOTIFY_FOCUS_RELEASED
Return Values
None
Reply Structure - Related Functions and Callbacks
SmGetFocusChangeReason
SmNfocusStateCallback
IBM ViaVoice SDK for Windows
SmGetGrammarPath
SmGetGrammarPath
Purpose
SmGetGrammarPath retrieves the full path name of an FSG file.
SmGetGrammarPath extracts data from the following reply message structure:
. SM_DEFINE_GRAMMAR_REPLY
Syntax
int SmGetGrammarPath (SM_MSG reply, char **grammar_path);
Parameters
reply
input - The reply structure from a SMAPI function.
grammar_path
output -The pointer to the full path name.
Return Values
SM_RC_OK
SM_RC_REPLY_NULL
SM_RC_SM_EINVAL_MSG_TYPE
Reply Structure - Related Functions and Callbacks
SmDefineGrammar
IBM SMAPI Reference
Data Access Functions
SmGetIncrements
Purpose
SmGetIncrements is used to retrieve an array of increment values from a reply structure. It is
valid only for the following message types:
. SM_QUERY_SCRIPTS_REPLY
Syntax
int SmGetIncrements (SM_MSG reply, unsigned long *nincrements,
short **increments);
Parameters
reply
input - The reply structure from a SMAPI function.
nincrements
output - Receives number of elements in array of increments returned.
increments
output - Receives array of increments.
Return Values
SM_RC_OK
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_REPLY_NULL
Reply Structure Related Functions and Callbacks
SmQueryScripts
Related Functions:
SmQueryScripts
IBM ViaVoice SDK for Windows
SmGetItemValue
SmGetItemValue
Purpose
SmGetItemValue retrieves the value for an item.
SmGetItemValue can extract data from the following reply message structures:
. SM_QUERY_REPLY
. SM_SET_REPLY
Syntax
int SmGetItemValue (SM_MSG reply, unsigned long *item,
unsigned long *value);
Parameters
reply
input - The reply structure from a SMAPI function.
item
output - The pointer to the name of the item.
value
output - The pointer to the value of the item.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQuery
SmSet
IBM SMAPI Reference
Data Access Functions
SmGetLanguages
Purpose
SmGetLanguages retrieves a list of languages.
SmGetLanguages can extract data from the following reply message structures:
. SM_CONNECT_REPLY
. SM_QUERY_ENROLLIDS_REPLY
. SM_QUERY_LANGUAGES_REPLY
. SM_QUERY_TASKS_REPLY
Syntax
int SmGetLanguages (SM_MSG reply, unsigned long *nlanguages,
char ***languages);
Parameters
reply
input - The reply structure from a SMAPI function.
nlanguages
output - The pointer to the number of languages.
languages
output - The pointer to a list of languages.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryEnrollIds
SmQueryLanguages
SmQueryTasks
SmConnect
IBM ViaVoice SDK for Windows
SmGetMicState
SmGetMicState
Purpose
SmGetMicState gets the microphone state.
SmGetMicState extracts the microphone state from one of the following messages sent by the
speech recognition engine to the application:
. SM_REPORT_ENGINE_ERROR
. SM_FOCUS_GRANTED
. SM_MIC_STATE
SM_REPORT_ENGINE_ERROR is unsolicited, and SM_FOCUS_GRANTED and
SM_MIC_STATE are sent if the application issues SmSet for SM_NOTIFY_FOCUS_STATE and
SM_NOTIFY_MIC_STATE, respectively.
Syntax
int SmGetMicState (SM_MSG reply, unsigned long *mic_state)
Parameters
reply
input - The reply structure from a SMAPI function.
mic_state
output - Pointer to an unsigned long, which can be any of the following:
SM_NOTIFY_MIC_ON
SM_ENGINE_MIC_OFF
Return Values
None
Reply Structure - Related Functions and Callbacks
SmNmicStateCallback
IBM SMAPI Reference
Data Access Functions
SmGetMsgName
Purpose
SmGetMsgName retrieves the name of the audio message.
SmGetMsgName can extract data from the following reply message structures:
. SM_PLAY_MESSAGE_STATUS
Syntax
int SmGetMsgName (SM_MSG reply, char **message_name);
Parameters
reply
input - The reply structure from a SMAPI function.
message_name
output - The pointer to the name of the audio message.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmNplayMessageStatusCallback
IBM ViaVoice SDK for Windows
SmGetMsgType
SmGetMsgType
Purpose
SmGetMsgType retrieves the type of message from the reply structure associated with the input.
The values for SMAPI message types are defined in the SMCOMM.H file and in the section
“SMAPI Message Types” on page 375.
SmGetMsgType can extract data from all defined reply message structures.
Syntax
int SmGetMsgType (SM_MSG reply, int *message_type);
Parameters
reply
input - The reply structure from a SMAPI function.
message_type
output - The message type.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
IBM SMAPI Reference
Data Access Functions
SmGetNameValue
Purpose
SmGetNameValue retrieves a name and its value.
SmGetNameValue retrieves a name (tag) of user information and its corresponding value. This
function can extract data from the following reply message structures:
. SM_QUERY_USER_INFO_REPLY
Syntax
int SmGetNameValue (SM_MSG reply, char **name, char **value);
Parameters
reply
input - The reply structure from a SMAPI function.
name
output -The pointer to the name.
value
output - The pointer to the value of the name.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryUserInfo
IBM ViaVoice SDK for Windows
SmGetNumberWordMsgs
SmGetNumberWordMsgs
Purpose
SmGetNumberWordMsgs gets the number of words from a message.
SmGetNumberWordMsgs retrieves the number of SM_RECOGNIZED_WORD messages that
have been sent since the last SM_RECOGNIZE_NEXT_WORD function call request. The value
returned is 0 or 1. This is used with a synchronous SM_HALT_RECOGNIZER_REPLY
message to tell if any unprocessed command words are still queued.
Syntax
int SmGetNumberWordMsgs (SM_MSG *reply, unsigned long *nwords);
Parameters
reply
input - The reply structure from a SMAPI function.
nwords
output - Pointer to an unsigned long that will be filled in with the number of words.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
IBM SMAPI Reference
Data Access Functions
SmGetOptions
Purpose
SmGetOptions is used to retrieve an options field from a reply structure. It is valid only for the
following message types:
. SM_DEFINE_VOCABULARY_REPLY
Syntax
int SmGetOptions (SM_MSG *reply, unsigned long *options);
Parameters
reply
input reply structure from a SMAPI function.
options
output -output - receives options field.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmDefineVocabEx
Related Functions:
SmDefineVocabEx
IBM ViaVoice SDK for Windows
SmGetPercentages
SmGetPercentages
Purpose
SmGetPercentages retrieves percentages of the completeness of processing for specified
enrollments.
SmGetPercentages can extract data from the following reply message structure:
. SM_QUERY_ENROLLIDS_REPLY
A query of enrollids for a given user returns an array of enrollids, with related fields, including
percent-complete. This procedure provides an array of the percent-complete values.
Syntax
int SmGetPercentages (SM_MSG reply, unsigned long *npercentages,
short **percentages);
Parameters
reply
input - The reply structure from a SMAPI function.
npercentages
output - The pointer to the number of percentages.
percentages
output -The pointer to a list of percentages.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryEnrollIds
IBM SMAPI Reference
Data Access Functions
SmGetPhraseScore
Purpose
SmGetPhraseScore is used to retrieve the phrase score from a reply structure. It is valid only for
the following message types:
. SM_RECOGNIZED_PHRASE
Syntax
int SmGetPhraseScore (SM_MSG reply, short *score);
Parameters
reply
inputinput -Reply structure from a SMAPI function.
score
output - Receives score of phrase.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmNrecognizedPhraseCallback
IBM ViaVoice SDK for Windows
SmGetPhraseState
SmGetPhraseState
Purpose
SmGetPhraseState retrieves phrase state flags.
SmGetPhraseState can extract data from the following reply message structure:
. SM_RECOGNIZED_PHRASE
Syntax
int SmGetPhraseState (SM_MSG reply, unsigned long *phrase_state);
Parameters
reply
input - The reply structure from a SMAPI function.
phrase_state
output - The pointer to an unsigned long which can be either of the following:
You can get both of the following as output:
. SM_PHRASE_HALTED
The engine is in a halted state and is waiting for the application to tell it what to do next.
. SM_PHRASE_ACCEPTED
The engine has accepted the phrase.
OR
You can get both of the following as output:
. SM_PHRASE_HALTED
The engine is in a halted state and is waiting for the application to tell it what to do next.
. SM_PHRASE_REJECTED
The engine has rejected the phrase, with the best guess phrase returned in the SM_WORD
array.
IBM SMAPI Reference
Data Access Functions
Return Values
SM_RC_OK
SM_RC_REPLY_NULL
SM_RC_SM_EINVAL_MSG_TYPE
Reply Structure - Related Functions and Callbacks
SmNRecognizedPhraseCallback
IBM ViaVoice SDK for Windows
SmGetPreferred
SmGetPreferred
Purpose
SmGetPreferred is used to retrieve the number of preferred topics from a reply structure. It is
valid only for the following message types:
. SM_QUERY_TOPICS_REPLY
Syntax
int SmGetPreferred (SM_MSG reply, short *preferred);
Parameters
reply
input - Reply structure from a SMAPI function.
preferred
output - Receives number of preferred topics.
Related Functions:
SmQueryTopics
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryTopics
IBM SMAPI Reference
Data Access Functions
SmGetPronunciations
Purpose
SmGetPronunciations retrieves pronunciations.
SmGetPronunciations can extract data from the following reply message structures:
. SM_QUERY_PRONUNCIATIONS_REPLY
. SM_WORD_CORRECTION_REPLY
. SM_QUERY_PRONUNCIATION_REPLY
. SM_RECOGNIZED_TEXT
Syntax
int SmGetPronunciations (SM_MSG reply, unsigned long *npronun,
char ***pronuns);
Parameters
reply
input - The reply structure from a SMAPI function.
npronun
output - The pointer to the number of pronunciations.
pronuns
output - The pointer to a list of pronunciations.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryPronunciations
SmWordCorrection
IBM ViaVoice SDK for Windows
SmGetRc
SmGetRc
Purpose
SmGetRc retrieves the return code for the SMAPI functions.
Syntax
int SmGetRc (SM_MSG reply, int *rc);
Parameters
reply
input - The reply structure from a SMAPI function.
rc
output - The pointer to the return code.
Return Values
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
All functions.
IBM SMAPI Reference
Data Access Functions
SmGetRcDescription
Purpose
SmGetRcDescription retrieves the ASCII string describing the return code.
SmGetRcDescription remaps return codes to ASCII strings that describe the return code and,
potentially, the associated failure. Messages are in US English only for diagnostic purposes. This
function returns a pointer to an ASCII character string that describes the return code in the
parameter rc_description. For example, for the symbolic return code
"SM_RC_ACOUSTICS_TOO_LONG", the associated return code description character string
would be "The acoustics specified are too long." For a list of all return code character strings,
reference “SMAPI Message Explanations” on page 379.
Syntax
int SmGetRcDescription (SM_MSG reply, char **rc_description);
Parameters
reply
input - The reply structure from a SMAPI function.
rc_description
output - Pointer to a character string.
Return Values
SM_RC_OK
SM_RC_REPLY_NULL
IBM ViaVoice SDK for Windows
SmGetRcName
SmGetRcName
Purpose
SmGetRcName returns the symbolic name of the return code as a string.
SmGetRcName retrieves the ASCII strings containing the symbol associated with the return code
as a string. For example, for a return code value of 49, the associated symbolic return code name
character string would be SM_RC_ACOUSTICS_TOO_LONG. For a list of all return code
values, reference “SMAPI Return Codes and Messages” on page 369.
Syntax
int SmGetRcName (SM_MSG reply, char **rc_name);
Parameters
reply
input - Any return code associated with any Sm call.
rc_name
output - Pointer to a character string.
Return Values
SM_RC_OK
SM_RC_REPLY_NULL
IBM SMAPI Reference
Data Access Functions
SmGetSampleRates
Purpose
SmGetSampleRates is used to retrieve an array of sample rates from a reply structure. It is valid
only for the following message types:
. SM_QUERY_ENROLLIDS_REPLY
Syntax
int SmGetSampleRates (SM_MSG reply, unsigned long *nrates,
short **sample_rates);
Parameters
reply
input - Reply structure from SMAPI function
nrates
output - Receives number of elements in array of sample_rates.
sample_rates
output - Receives array of sample_rates.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryEnrollids
Related Functions
SmQueryEnrollids
IBM ViaVoice SDK for Windows
SmGetScriptFlags
SmGetScriptFlags
Purpose
SmGetScriptFlags is used to retrieve an array of script flags from a reply structure. It is valid only
for the following message types:
. SM_QUERY_SCRIPTS_REPLY
Syntax
int SmGetScriptFlags (SM_MSG reply, unsigned long *nflags, long **flags);
Parameters
reply
input - Reply structure from SMAPI function
nflags
output - Receives number of elements in array of flags.
flags
output - Receives array of flags.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryScripts
Related Functions
SmQueryScripts
IBM SMAPI Reference
Data Access Functions
SmGetScripts
Purpose
SmGetScripts retrieves a list of enrollment scripts.
SmGetScripts can extract data from the following reply message structures:
. SM_QUERY_SCRIPTS_REPLY
. SM_QUERY_ENROLLIDS_REPLY
Syntax
int SmGetScripts (SM_MSG reply, unsigned long *nscripts, char ***scripts);
Parameters
reply
input - The reply structure from a SMAPI function.
nscripts
output - The pointer to the number of scripts.
scripts
output -The pointer to a list of scripts.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryEnrollIds
IBM ViaVoice SDK for Windows
SmGetService
SmGetService
Purpose
SmGetService retrieves a pointer to the argument name describing the service requested from the
speech recognition engine.
SmGetService can extract data from the following reply message structures:
. SM_CONNECT_REPLY
. SM_DISCONNECT_REPLY
Syntax
int SmGetService (SM_MSG reply, char **service);
Parameters
reply
input - The reply structure from a SMAPI function.
service
output - The pointer to the service name.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmConnect
SmDisconnect
IBM SMAPI Reference
Data Access Functions
SmGetSessionId
Purpose
SmGetSessionId retrieves the session ID from the reply structure.
SmGetSessionId can extract data from the following reply message structure:
. SM_CONNECT_REPLY
Syntax
int SmGetSessionId (SM_MSG reply, char **session_id);
Parameters
reply
input - The reply structure from a SMAPI function.
session_id
output - The pointer to the ID of the session.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmConnect
IBM ViaVoice SDK for Windows
SmGetSeverity
SmGetSeverity
Purpose
SmGetSeverity retrieves the severity associated with an unsolicited
SM_REPORT_ENGINE_ERROR message.
Syntax
int SmGetSeverity (SM_MSG reply, unsigned long *severity);
Parameters
reply
input - The reply structure from a SMAPI function.
severity
output -Pointer to an unsigned long that will be filled in with the severity. Values include the
following:
SM_ENGINE_INFO
Informational message/can be ignored.
SM_ENGINE_WARNING
Non-terminal error detected by engine.
SM_ENGINE_ERROR
Currently unused, but can be used in the future.
SM_ENGINE_TERMINAL_ERROR
Engine terminated due to unrecoverable error.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
IBM SMAPI Reference
Data Access Functions
SmGetSizes
Purpose
SmGetSizes is used to retrieve an array of size values from a reply structure. It is valid only for the
following message types:
. SM_QUERY_SCRIPTS_REPLY
Syntax
int SmGetSizes (SM_MSG reply, unsigned long *nsizes, short **sizes);
Parameters
reply
input - Reply structure from a SMAPI function.
nsizes
output - Receives number of elements in array of sizes Non-terminal error detected by engine.
sizes
output - Receives array of sizes.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryScripts
Related Functions:
SmQueryScripts
IBM ViaVoice SDK for Windows
SmGetSpeechDataArchive
SmGetSpeechDataArchive
Purpose
SmGetSpeechDataArchive retrieves the name of the archive file.
SmGetSpeechDataArchive extracts data associated with the following reply message structures:
. SM_SAVE_SPEECH_DATA_REPLY
. SM_RESTORE_SPEECH_DATA_REPLY
Syntax
int SmGetSpeechDataArchive (SM_MSG reply, char **archive);
Parameters
reply
input - The reply structure from a SMAPI function.
archive
output -The pointer to the archive name.
Return Values
SM_RC_OK
SM_RC_REPLY_NULL
SM_RC_SM_EINVAL_MSG_TYPE
Reply Structure - Related Functions and Callbacks
SmSaveSpeechData
SmRestoreSpeechData
IBM SMAPI Reference
Data Access Functions
SmGetSpeechDataOptions
Purpose
SmGetSpeechDataOptions retrieves the options flags.
SmGetSpeechDataOptions extracts data associated with the following reply message structure:
. SM_SAVE_SPEECH_DATA_REPLY
Syntax
int SmGetSpeechDataOptions (SM_MSG reply, long *options);
Parameters
reply
input - The reply structure from a SMAPI function.
options
output -The pointer to the options flags, which can be one of the following:
SM_NORMAL_FILE
This indicates that the speech data was written to a flat file. It will contain only engine data.
SM_COMPOUND_FILE
This indicates that the speech data is written to a Windows compound file, and the data is
saved in a section named "VTDSessionArchive." The file can contain both engine state and
application state data.
Return Values
SM_RC_OK
SM_RC_REPLY_NULL
SM_RC_SM_EINVAL_MSG_TYPE
Reply Structure - Related Functions and Callbacks
SmSaveSpeechData
IBM ViaVoice SDK for Windows
SmGetSpeechDataSize
SmGetSpeechDataSize
Purpose
SmGetSpeechDataSize retrieves the size of the speech data archive.
SmGetSpeechDataSize extracts data associated with the following reply message structures:
. SM_SAVE_SPEECH_DATA_REPLY
. SM_QUERY_SPEECH_DATA_REPLY
Syntax
int SmGetSpeechDataSize (SM_MSG reply, unsigned long *size);
Parameters
reply
input - The reply structure from a SMAPI function.
size
output - The pointer to the size of the speech data archive.
Return Values
SM_RC_OK
SM_RC_REPLY_NULL
SM_RC_SM_EINVAL_MSG_TYPE
Reply Structure - Related Functions and Callbacks
SmQuerySpeechData
SmSaveSpeechData
IBM SMAPI Reference
Data Access Functions
SmGetSpeechDataVersion
Purpose
SmGetSpeechDataVersion retrieves the version identifier.
SmGetSpeechDataVersion extracts data associated with the following reply message structures:
. SM_SAVE_SPEECH_DATA_REPLY
. SM_RESTORE_SPEECH_DATA_REPLY
Syntax
int SmGetSpeechDataVersion (SM_MSG reply, long *version);
Parameters
reply
input - The reply structure from a SMAPI function.
version
output - The pointer to the version identifier.
Return Values
SM_RC_OK
SM_RC_REPLY_NULL
SM_RC_SM_EINVAL_MSG_TYPE
Reply Structure - Related Functions and Callbacks
SmRestoreSpeechData
SmSaveSpeechData
IBM ViaVoice SDK for Windows
SmGetSpelling
SmGetSpelling
Purpose
SmGetSpelling gets the spelling from a message.
SmGetSpelling extracts data and retrieves the spelling associated with the following reply
message structures:
. SM_ADD_PRONUNCIATION_REPLY
. SM_AUTO_COMPLETE_REPLY
. SM_QUERY_PRONUNCIATION_REPLY
. SM_QUERY_SPELLING_REPLY
. SM_QUERY_TOPICS_REPLY
. SM_QUERY_USER_DEFAULT_REPLY
. SM_REMOVE_PRONUNCIATION_REPLY
Syntax
int SmGetSpelling (SM_MSG reply, char **spelling);
Parameters
reply
input - The reply structure from a SMAPI function.
spelling
output - Pointer to a character string.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
IBM SMAPI Reference
Data Access Functions
Reply Structure - Related Functions and Callbacks
SmAddPronunciation
SmQueryPronunciation
SmRemovePronunciation
SmWordCorrection
IBM ViaVoice SDK for Windows
SmGetSpellings
SmGetSpellings
Purpose
SmGetSpellings retrieves spellings.
SmGetSpellings extracts data and retrieves the spelling associated with the following reply
message structures:
. SM_ADD_PRONUNCIATION_REPLY
. SM_QUERY_PRONUNCIATIONS_REPLY
. SM_REMOVE_PRONUNCIATION_REPLY
. SM_WORD_CORRECTION_REPLY
Syntax
int SmGetSpellings (SM_MSG reply, unsigned long *nspellings,
char ***spellings);
Parameters
reply
input - The reply structure from a SMAPI function.
nspellings
output -The pointer to the number of spellings.
spellings
output - The pointer to a list of spellings.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
IBM SMAPI Reference
Data Access Functions
Reply Structure - Related Functions and Callbacks
SmAddPronunciation
SmQueryPronunciations
SmRemovePronunciation
SmWordCorrection
IBM ViaVoice SDK for Windows
SmGetStates
SmGetStates
Purpose
SmGetStates retrieves enrollment statuses.
SmGetStates can extract data from the following reply message structure:
. SM_QUERY_ENROLLIDS_REPLY
. SM_QUERY_SCRIPTS_REPLY
Syntax
int SmGetStates (SM_MSG reply, unsigned long *nstati, short **stati);
Parameters
reply
input - The reply structure from a SMAPI function.
nstati
output -The pointer to the number of statuses.
stati
output -The pointer to a list of statuses. Values include the following:
. SM_STAT_ENROLLMENT_RECORDING
. SM_STAT_ENROLLMENT_RUNNING
. SM_STAT_ENROLLMENT_COMPLETE
. SM_STAT_ENROLLMENT_FAILED
. SM_STAT_ENROLLMENT_BUSY
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure Functions by Message Type
SmQueryEnrollIds
IBM SMAPI Reference
Data Access Functions
SmGetStatus
Purpose
SmGetStatus retrieves the status.
SmGetStatus can extract data from the following reply message structures:
. SM_DISCARD_SPEECH_DATA_REPLY
. SM_PLAY_MESSAGE_STATUS
. SM_PLAY_UTTERANCE_STATUS
. SM_PLAY_WORDS_STATUS
. SM_WORD_CORRECTION_REPLY
The SmGetStatus function retrieves the status from the reply structure. This status and its
meaning depend on the related function that was called just before the SmGetStatus call. The
following statuses are possible:
. For SmNplayMessageCallback and SmNplayUtteranceCallback:
SM_STAT_PLAY_START
The message, utterance, or word playback started.
SM_STAT_PLAY_STOP
The message, utterance, or word playback stopped.
. For SmNplayWordsStatusCallback:
SM_STAT_PLAY_START
The message, utterance, or word playback started.
SM_STAT_PLAY_STOP
The message, utterance, or word playback stopped.
SM_STAT_BAD_AUDIO
The connection to the audio source was lost during playback.
SM_STAT_BAD_TAG
An invalid tag value was specified for the word.
. For an SmWordCorrection call:
SM_RC_ADDED
The word was added to the vocabulary.
IBM ViaVoice SDK for Windows
SmGetStatus
SM_RC_INVOCAB
The word is already in the vocabulary.
SM_RC_NOT_INVOCAB
The word is not in the IBM ViaVoice spelling dictionary.
SM_RC_NOT_ADDED
The word has not been added to the vocabulary.
Syntax
int SmGetStatus (SM_MSG reply, int *status);
Parameters
reply
input - The reply structure from a SMAPI function.
status
output - The pointer to the status.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmWordCorrection
SmNplayMessageStatusCallback
SmNplayUtteranceStatusCallback
SmNplayWordsStatusCallback
IBM SMAPI Reference
Data Access Functions
SmGetTags
Purpose
SmGetTags retrieves tags from the reply structure.
SmGetTags can extract data from the following reply message structures:
. SM_PLAY_WORDS_STATUS
. SM_QUERY_ALTERNATES_REPLY
. SM_WORD_CORRECTION_REPLY
Syntax
int SmGetTags (SM_MSG reply, unsigned long *ntags, long **tags);
Parameters
reply
input - The reply structure from a SMAPI function.
ntags
output -The pointer to the number of tags.
tags
output -The pointer to a list of tags.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryAlternates
SmWordCorrection
SmNplayWordsStatusCallback
IBM ViaVoice SDK for Windows
SmGetTask
SmGetTask
Purpose
SmGetTask retrieves a domain from the reply structure.
SmGetTask is valid only for reply message structures that contain one domain. Use SmGetTasks
for reply message structures with multiple domains. SmGetTask can extract data from the
following reply message structures:
. SM_CONNECT_REPLY
. SM_QUERY_DEFAULT_REPLY
. SM_QUERY_TASKS_REPLY
. SM_QUERY_USER_DEFAULT_REPLY
Syntax
int SmGetTask (SM_MSG reply, char **domain);
Parameters
reply
input - The reply structure from a SMAPI function.
domain
output - The pointer to a domain.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryDefault
SmQueryTasks
IBM SMAPI Reference
Data Access Functions
SmGetTaskFlags
Purpose
SmGetTaskFlags retrieves attribute information about tasks.
SmGetTaskFlags extracts the task attribute flags from the SM_QUERY_TASKS_REPLY reply
message sent by the speech recognition engine to the application
Syntax
int SmGetTaskFlags (SM_MSG reply, unsigned long *nflags,
unsigned long **flags);
Parameters
reply
input - The reply structure from a SMAPI function.
nflags
output -A pointer to the number of flags in the list of return flags.
flags
output - A pointer to a list of task flags. Each flag in the list contains information about one or
more of the following attributes of a task:
. SM_TASK_CONTINUOUS -This task supports continuous dictation
. SM_TASK_NUMBER_FMT - This task supports number formatting
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure Functions by Message Type
SMQueryTasks
Task Related Functions and Callbacks
SmNqueryTasksCallback
IBM ViaVoice SDK for Windows
SmGetTasks
SmGetTasks
Purpose
SmGetTasks retrieves domains from the reply structure.
SmGetTasks extracts data from the following reply message structures:
. SM_CONNECT_REPLY
. SM_QUERY_DEFAULT_REPLY
. SM_QUERY_SCRIPTS_REPLY
. SM_QUERY_SESSIONS_REPLY
. SM_QUERY_TASKS_REPLY
. SM_QUERY_USER_DEFAULT_REPLY
Syntax
int SmGetTasks (SM_MSG reply, unsigned long *ndomains, char ***domains);
Parameters
reply
input - The reply structure from a SMAPI function.
ndomains
output -The pointer to the number of domains.
domains
output -The pointer to a list of domains.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryTasks
IBM SMAPI Reference
Data Access Functions
SmGetTimes
This API call is ONLY here for compatibility purposes. If you are writing a new application, you
should use SmGetWordTimes instead to return the start and end times for text, word, and phrase
messages.
Purpose
SmGetTimes retrieves time values of spoken words.
SmGetTimes retrieves an array of time values sent with words received in the last
SM_RECOGNIZED_TEXT or SM_RECOGNIZED_WORD message from the speech
recognition engine. Each time, expressed in milliseconds, specifies the time elapsed from the
beginning of the utterance to the beginning of the spoken word. This function can extract data from
the following reply message structures:
. SM_RECOGNIZED_TEXT
. SM_RECOGNIZED_WORD
Syntax
int SmGetTimes(SM_MSG reply, unsigned long *ntimes, unsigned long **times);
Parameters
reply
input - The reply structure from a SMAPI function.
ntimes
output - The pointer to the number of times in the list.
times
output - The pointer to a list of times.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
IBM ViaVoice SDK for Windows
SmGetTimes
Reply Structure - Related Functions and Callbacks
SmNrecognizedTextCallback
SmNrecognizedWordCallback
SmNaudioEventCallback
IBM SMAPI Reference
Data Access Functions
SmGetTopics
Purpose
SmGetTopics is used to retrieve an array of topics from a reply structure. It is valid only for the
following message types:
. SM_QUERY_TOPICS_REPLY
. SM_SET_TOPICS_REPLY
Syntax
int SmGetTopics (SM_MSG reply, unsigned long *ntopics, char ***topics);
Parameters
reply
input -reply structure from a SMAPI function.
ntopics
output - receives number of elements in array of topics
trained
output - receives array of topics.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryTopics
Related Functions:
SmQueryTopics
IBM ViaVoice SDK for Windows
SmGetTrained
SmGetTrained
Purpose
SmGetTrained is used to retrieve an array of trained values from a reply structure. It is valid only
for the following message types:
. SM_QUERY_SCRIPTS_REPLY
Syntax
int SmGetTrained (SM_MSG reply, unsigned long *ntrained, short **trained);
Parameters
reply
input -reply structure from a SMAPI function.
ntrained
output - receives number of elements in array of trained
trained
output - receives array of trained.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryScripts
Related Functions:
SmQueryScripts
IBM SMAPI Reference
Data Access Functions
SmGetUserId
Purpose
SmGetUserId retrieves a user ID from the reply structure.
SmGetUserId is valid only for reply message structures that contain one user ID. Use
SmGetUserIds for reply message structures with multiple user IDs. SmGetUserId can extract
data from the following reply message structures:
. SM_CONNECT_REPLY
. SM_QUERY_DEFAULT_REPLY
. SM_QUERY_USER_INFO_REPLY
. SM_QUERY_USER_DEFAULT_REPLY
. SM_REQUEST_NEW_ENROLLID_REPLY
. SM_REQUEST_NEW_USERID_REPLY
. SM_SET_USER_INFO_REPLY
Syntax
int SmGetUserId (SM_MSG reply, char **user_id);
Parameters
reply
input - The reply structure from a SMAPI function.
user_id
output - The pointer to a user ID.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
IBM ViaVoice SDK for Windows
SmGetUserId
Reply Structure - Related Functions and Callbacks
SmQueryDefault
SmQueryUserInfo
SmQueryUsers
SmSetUserInfo
IBM SMAPI Reference
Data Access Functions
SmGetUserIds
Purpose
SmGetUserIds retrieves user IDs from the reply structure.
SmGetUserIds can extract data from the following reply message structures:
. SM_QUERY_DEFAULT_REPLY
. SM_QUERY_SESSIONS_REPLY
. SM_QUERY_USER_DEFAULT_REPLY
. SM_QUERY_USER_INFO_REPLY
. SM_QUERY_USERS_REPLY
. SM_REQUEST_NEW_ENROLLID_REPLY
. SM_REQUEST_NEW_USERID_REPLY
. SM_SET_USER_INFO_REPLY
Syntax
int SmGetUserIds(SM_MSG reply, unsigned long *nuser_ids, char ***user_ids);
Parameters
reply
input - The reply structure from a SMAPI function.
nuser_ids
output - The pointer to the number of user IDs.
user_ids
output -The pointer to a list of user IDs.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
IBM ViaVoice SDK for Windows
SmGetUserIds
Reply Structure - Related Functions and Callbacks
SmQueryUserInfo
SmQueryUsers
SmSetUserInfo
IBM SMAPI Reference
Data Access Functions
SmGetUsers
Purpose
SmGetUsers retrieves users from the reply structure.
SmGetUsers can extract data from the following reply message structure:
. SM_QUERY_USERS_REPLY
. SM_REQUEST_NEW_USERID_REPLY
Syntax
int SmGetUsers (SM_MSG reply, unsigned long *nusers, char ***users);
Parameters
reply
input - The reply structure from a SMAPI function.
nusers
output - The pointer to the number of users.
users
output -The pointer to a list of users.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryUsers
IBM ViaVoice SDK for Windows
SmGetUtteranceNumber
SmGetUtteranceNumber
Purpose
SmGetUtteranceNumber retrieves the utterance number from the reply structure.
SmGetUtteranceNumber can extract data from the following reply message structures:
. SM_MIC_ON_REPLY
. SM_PLAY_UTTERANCE_STATUS
. SM_UTTERANCE_COMPLETED
Syntax
int SmGetUtteranceNumber (SM_MSG reply, unsigned long *nutterance);
Parameters
reply
input - The reply structure from a SMAPI function.
nutterance
output - The pointer to the utterance number.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmMicOn
SmNplayUtteranceStatusCallback
SmNutteranceCompletedCallback
IBM SMAPI Reference
Data Access Functions
SmGetVocabList
Purpose
SmGetVocabList function retrieves a vocabulary list from the reply structure.
SmGetVocabList can extract data from the following reply message structures:
. SM_QUERY_ENABLED_VOCABS_REPLY
. SM_QUERY_VOCABS_REPLY
. SM_QUERY_WORD_REPLY
. SM_SET_VOCABS_REPLY
Syntax
int SmGetVocabList (SM_MSG reply, unsigned long *nvocabs,
char ***vocabs);
Parameters
reply
input - The reply structure from a SMAPI function.
nvocabs
output - The pointer to the number of vocabularies in the vocabulary list.
vocabs
output -The pointer to a list of vocabularies.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryEnabledVocabs
SmQueryVocabs
SmQueryWord
IBM ViaVoice SDK for Windows
SmGetVocabName
SmGetVocabName
Purpose
SmGetVocabName retrieves the vocabulary name from the reply structure.
SmGetVocabName extracts data from the following reply message structures:
. SM_ADD_TO_VOCAB_REPLY
. SM_DEFINE_GRAMMAR_REPLY
. SM_DEFINE_VOCAB_REPLY
. SM_DEFINE_VOCABULARY_REPLY
. SM_DISABLE_VOCAB_REPLY
. SM_ENABLE_VOCAB_REPLY
. SM_QUERY_PHRASE_ALTERNATES_REPLY
. SM_RECOGNIZED_PHRASE
. SM_REMOVE_FROM_VOCAB_REPLY
. SM_UNDEFINE_VOCAB_REPLY
Syntax
int SmGetVocabName (SM_MSG reply, char **vocabname);
Parameters
reply
input - The reply structure from a SMAPI function.
vocabname
output - The pointer to the name of the vocabulary.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
IBM SMAPI Reference
Data Access Functions
Reply Structure - Related Functions and Callbacks
SmAddToVocab
SmDefineVocab
SmDisableVocab
SmEnableVocab
SmRemoveFromVocab
SmUndefineVocab
IBM ViaVoice SDK for Windows
SmGetVocabPath
SmGetVocabPath
Purpose
SmGetVocabPath is used to retrieve a vocabulary path from a reply structure. It is valid only for
the following message types:
. SM_DEFINE_VOCABULARY_REPLY
Syntax
int SmGetVocabPath (SM_MSG reply, char **vocab_path);
Parameters
reply
input - reply structure from a SMAPI function.
vocab_path
output - receives vocabulary path string.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmDefineVocabEx
Related Functions
SmDefineVocabEx
IBM SMAPI Reference
Data Access Functions
SmGetVocWords
Purpose
SmGetVocWords retrieves vocabulary words from the reply structure.
SmGetVocWords extracts data from the following reply message structures:
. SM_ADD_TO_VOCAB_REPLY
. SM_DEFINE_GRAMMAR_REPLY
. SM_DEFINE_VOCAB_REPLY
. SM_DEFINE_VOCABULARY_REPLY
. SM_QUERY_VOCAB_WORDS_REPLY
Following an SmAddToVocab call, SmGetVocWords extracts the vocabulary words that failed to
be added.
Following an SmDefineVocab call, SmGetVocWords extracts the vocabulary words that failed to
be defined.
For a description of the SM_VOCWORD data type, reference “SM_VOCWORD” on page 302.
Syntax
int SmGetVocWords (SM_MSG reply, unsigned long *nwords,
SM_VOCWORD **words);
Parameters
reply
input - The reply structure from a SMAPI function.
nwords
output -The pointer to the number of vocabulary words. Limited to SM_MAX_VOCWORDS.
words
output -The pointer to a list of vocabulary words.
IBM ViaVoice SDK for Windows
SmGetVocWords
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmAddToVocab
SmDefineVocab
IBM SMAPI Reference
Data Access Functions
SmGetWords
Purpose
SmGetWords retrieves words from the reply structure.
SmGetWords can extract data from the following reply message structures:
. SM_QUERY_ADDED_WORDS_REPLY
. SM_QUERY_WORD_REPLY
Syntax
int SmGetWords (SM_MSG reply, unsigned long *nwords, SM_WORD **words);
Parameters
reply
input - The reply structure from a SMAPI function.
nwords
output - The pointer to the number of words.
words
output -The pointer to a list of words.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmQueryAddedWords
SmQueryWord
IBM ViaVoice SDK for Windows
SmGetWordTimes
SmGetWordTimes
Purpose
SmGetWordTimes retrieves the most likely start and end times for recognized words from the
reply structure.
During recognition, the speech recognition engine computes the most likely start and end times for
each recognized word. These times are used for playback and for computing alternates for word
correction.
The times returned by SmGetWordTimes are reported in frame time since the beginning of an
utterance, not clock time. Frame time is essentially in centiseconds (hundredths of a second), but
there can be slight differences in frame time versus clock time depending on the sample rate. For
example, at 11025Hz sampling, a frame is represented by 110 samples, so there is a drift of 11000/
11025 between frame time and clock time.
SmGetWordTimes can extract data from the following reply message structures:
. SM_ADD_PRONUNCIATION_REPLY
. SM_QUERY_PHRASE_ALTERNATIVES_REPLY
. SM_RECOGNIZED_PHRASE
. SM_RECOGNIZED_TEXT
. SM_RECOGNIZED_WORD
Syntax
int SmGetWordTimes (SM_MSG reply, unsigned long *ntimes,
unsigned long **stimes, unsigned long **etimes);
Parameters
reply
input - The reply structure from one of the supported messages.
ntimes
output - The pointer to the number of times in the list.
stimes
output -The pointer to the list of start times.
IBM SMAPI Reference
Data Access Functions
etimes
output -The pointer to the list of end times.
Return Values
SM_RC_SM_EINVAL_MSG_TYPE
SM_RC_OK
SM_RC_REPLY_NULL
Reply Structure - Related Functions and Callbacks
SmNrecognizedPhraseCallback
SmNrecognizedTextCallback
SmNrecognizedWordCallback
IBM ViaVoice SDK for Windows
SmReturnRc
SmReturnRc
Purpose
SmReturnRc returns the return code from SM_MSG.
SmReturnRc provides an alternative to SmGetRc for accessing return codes from messages
received from the speech recognition engine. The return value of the function is the return code
value in the given SM_MSG.
Syntax
int SmReturnRc (SM_MSG reply);
Parameters
reply
input - The reply structure from a SMAPI function.
Return Values
SM_RC_OK
SM_RC_REPLY_NULL
Task Related Functions and Callbacks
SmReturnRcDescription
SmReturnRcName
IBM SMAPI Reference
Data Access Functions
SmReturnRcDescription
Purpose
SmReturnRcDescription retrieves the ASCII string describing the return code.
SmReturnRcDescription remaps return codes to ASCII strings that describe the return code and,
potentially, the associated failure. Messages are in US English only for diagnostic purposes. For
example, if this function were passed the return code, SM_RC_ACOUSTICS_TOO_LONG, a
pointer to the associated return code description character string "The acoustics specified are too
long." would be returned. For a list of all return code character strings, reference “SMAPI Message
Explanations” on page 379.
Syntax
char *SmReturnRcDescription (int rc);
Parameters
rc
input - Any return code associated with any Sm call.
Task Related Functions and Callbacks
SmReturnRc
SmReturnRcName
IBM ViaVoice SDK for Windows
SmReturnRCName
SmReturnRCName
Purpose
SmReturnRcName returns the symbolic name of a return code as a string.
SmReturnRcName provides an alternative to SmGetRcName for retrieving an ASCII string
containing the symbol associated with a return code. For example, if this function was passed the
return code, SM_RC_ACOUSTICS_TOO_LONG, a pointer to the associated symbolic return
code name character string "SM_RC_ACOUSTICS_TOO_LONG" would be returned. For a list of
all return code values, reference “SMAPI Return Codes and Messages” on page 369.
Syntax
char *SmReturnRcName (int rc);
Parameters
rc
input - Any return code associated with any Sm call.
Return Values
Function directly returns a pointer to a statically defined character string containing a description
associated with the return code.
Refer to Appendix A. "SMAPI Return Codes and Messages" for a complete list of the character
strings, their associated return values, and their symbolic return code names.
Task Related Functions and Callbacks
SmReturnRc
SmReturnRcDescription
IBM SMAPI Reference
Data Access Functions
IBM ViaVoice SDK for Windows
Chapter 5 Reply Message Structures and
Callbacks
This chapter describes reply structures and callbacks.
Reply Message Structures Received from the Speech
Recognition Engine
An application can receive the following reply message structures, defined in SMCOMM.H, from the
speech recognition 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_AUTO_COMPLETE_REPLY X Response to an asynchronous
SmAddComplete call. Data can
be extracted with SmGetFlags,
SmGetSpelling or
SmGetSpellings.
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.
IBM SMAPI Reference
Reply Message Structures and Callbacks
Reply Message Structure Solicited Unsolicited Explanation
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_W
ORD, 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,
SmGetNumberUtterances,
SmGetService, SmGetSessionId,
SmGetTask, SmGetTasks,
SmGetUserId, or SmGetUserIds.
SM_CORRECT_TEXT_REPLY X Response to an asynchronous
SmCorrectText call.
SM_DEFINE_GRAMMAR_REPLY X Response to an asynchronous
SmDefineGrammar call. Data
can be extracted with
SmSetGrammarPath.
IBM ViaVoice SDK for Windows
Reply Message Structures Received from the Speech Recognition Engine
Reply Message Structure Solicited Unsolicited Explanation
SM_DEFINE_VOCAB_REPLY X Response to an asynchronous
SmDefineVocab call. Data can
be extracted with
SmGetVocabName or
SmGetVocWords.
SM_DEFINE_VOCABULARY_REPLY X Response to an asynchronous
SmDefineVocab call. Data can
be extracted with
SmGetVocabName,
SmGetVocWords,
SmGetVocabPath, or
SmGetOptions.
SM_DETACH_SESSIONS_REPLY X Response to an asynchronous
SmDetachSessions call.
SM_DISCARD_DATA_REPLY X Response to an asynchronous
SmDiscardData call.
SM_DISCARD_SPEECH_DATA_REPLY X Response to an asynchronous
SmDiscardSpeechData call.
Data can be extracted with
SmGetFlags or SmGetStatus.
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 SM_NOTIFY_ENGINE_STATE
is controlled by SmSet and this
message indicates current engine
status and synchronizes the
display and the engine state. The
SmGetEngineState function
extracts the data.
IBM SMAPI Reference
Reply Message Structures and Callbacks
Reply Message Structure Solicited Unsolicited Explanation
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.
SmGetFocusChangeReason
extracts the focus change reason.
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.
IBM ViaVoice SDK for Windows
Reply Message Structures Received from the Speech Recognition Engine
Reply Message Structure Solicited Unsolicited Explanation
SM_REQUEST_MIC_OFF X Request to turn off the
microphone.
SM_REQUEST_MIC_ON 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_STA
TUS 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.
IBM SMAPI Reference
Reply Message Structures and Callbacks
Reply Message Structure Solicited Unsolicited Explanation
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.
IBM ViaVoice SDK for Windows
Reply Message Structures Received from the Speech Recognition Engine
Reply Message Structure Solicited Unsolicited Explanation
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_PHRASE_ALTERNATIVES_REPLY X Response to an asynchronous
SmQueryPhraseAlternatives
call. Data can be extracted with
SmGetFirmWords,
SmGetVocabName,
SmGetAnnotations,
SmGetWordTimes, and
SmGetPhraseState.
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
SmQueryPronunciationsEx 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.
IBM SMAPI Reference
Reply Message Structures and Callbacks
Reply Message Structure Solicited Unsolicited Explanation
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. Data
can be extracted with
SmGetSpeechDataSize.
SM_QUERY_TASKS_REPLY X Response to an asynchronous
SmQueryTasks call. Data can be
extracted with SmGetAlphabets,
SmGetDescriptions,
SmGetLanguages or
SmGetTasks.
SM_QUERY_TOPICS_REPLY X Response to an asynchronous
SmQueryTopics call. Data can
be extracted from SmGetTopics,
SmGetPreferred,
SmGetDescriptions, or
SmGetFlags.
SM_QUERY_USER_DEFAULT_REPLY X Response to an asynchronous
SmQueryUserDefault call. Data
can be extracted with
SmGetUserId, SmGetUserIds,
SmGetEnrollId,
SmGetEnrollIds, SmGetTask,
SmGetTasks, or
SmGetDefaultTopics.
SM_QUERY_USER_INFO_REPLY X Response to an asynchronous
SmQueryUserInfo call. Data can
be extracted with
SmGetEnrollId,
SmGetEnrollIds,
SmGetNameValue,
SmGetUserId, or SmGetUserIds.
IBM ViaVoice SDK for Windows
Reply Message Structures Received from the Speech Recognition Engine
Reply Message Structure Solicited Unsolicited Explanation
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,
SmGetAnnotations, and
SmGetWordTimes.
SM_RECOGNIZED_TEXT X Includes infirm or firm words or
both sent during dictation
vocabulary recognition. Data can
be extracted with
SmGetFirmWords,
SmGetInfirmWords,
SmGetTimes, and
SmGetWordTimes.
SM_RECOGNIZED_WORD X Includes firm words sent during
command vocabulary
recognition. Data can be
extracted with SmGetAlternates,
SmGetFirmWords, SmGetTimes
and SmGetWordTimes.
IBM SMAPI Reference
Reply Message Structures and Callbacks
Reply Message Structure Solicited Unsolicited Explanation
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
recognition 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. Data
can be extracted using
SmGetSpeechDataArchive.
IBM ViaVoice SDK for Windows
Reply Message Structures Received from the Speech Recognition Engine
Reply Message Structure Solicited Unsolicited Explanation
SM_SAVE_SPEECH_DATA_REPLY X Response to an asynchronous
SmSaveSpeechData call. Data
can be extracted using
SmGetSpeechDataArchive,
SmGetSpeechDataOptions, or
SmGetSpeechDataSize.
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_DEFAULT_REPLY X Response to an asynchronous
SmSetUserDefault call. No data
returned.
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.
IBM SMAPI Reference
Reply Message Structures and Callbacks
Callbacks
The following callbacks are available for processing messages from the router and the speech
recognition engine.
Callback Solicited Unsolicited Message Type
SmNautoCompleteCallback X SM_AUTO_COMPLETE_REPLY
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
SmNdefineVocabExCallback X SM_DEFINE_VOCABULARY_REPLY
SmNdetachRequestedCallback X SM_REQUEST_DETACH
SmNdetachSessionsCallback X SM_DETACH_SESSIONS_REPLY
SmNdisableVocabCallback X SM_DISABLE_VOCAB_REPLY
SmNdiscardDataCallback X SM_DISCARD_DATA_REPLY
SmNdiscardSpeechDataCallback X SM_DISCARD_SPEECH_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
IBM ViaVoice SDK for Windows
Callbacks
SmNfocusLostCallback X SM_FOCUS_LOST
SmNfocusStateCallback X SM_FOCUS_STATE
SmNhaltRecognizerCallback X SM_HALT_RECOGNIZER_REPLY
SmNmicOffCallback X SM_REQUEST_MIC_OFF
SmNmicOnCallback X SM_REQUEST_MIC_ON
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
SmNqueryAddedWordsExCallback 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
SmNqueryPhraseAlternativesCallbac
k
X SM_QUERY_ADDED_WORDS_REPLY
SmNqueryPronunciationCallback X SM_QUERY_PRONUNCIATION_REPLY
SmNqueryPronunciationsCallback X SM_QUERY_PRONUNCIATIONS_REPLY
SmNqueryPronunciationsExCallback X SM_QUERY_PRONUNCIATIONS_REPLY
SmNquerySessionsCallback X SM_QUERY_SESSIONS_REPLY
SmNquerySpeechDataCallback X SM_QUERY_SPEECH_DATA_REPLY
SmNqueryTasksCallback X SM_QUERY_TASKS_REPLY
IBM SMAPI Reference
Reply Message Structures and Callbacks
SmNqueryTopicsCallback X SM_QUERY_TOPICS_REPLY
SmNqueryUsersCallback X SM_QUERY_USERS_REPLY
SmNqueryUserDefaultCallback X SM_QUERY_USER_DEFAULT_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
SmNsetUserDefaultCallback X SM_SET_USER_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
IBM ViaVoice SDK for Windows
Reply Structure Functions for Unsolicited Callbacks
Reply Structure Functions for Unsolicited Callbacks
The following is a list of all unsolicited callbacks available for processing messages from the speech
recognition engine. Each callback is followed by a list of the reply structure functions that can be
called from within it.
. SmNaudioLevelCallback
. SmGetRc
. SmGetAudioLevel
. SmGetTimes
. SmNcommandWordCallback
. SmGetRc
. SmGetApplication
. SmGetFirmWords
. SmNdetachRequestedCallback
. SmGetRc
. SmNengineStateCallback
. SmGetRc
. SmGetengineState
. SmGetTimes
IBM SMAPI Reference
Reply Message Structures and Callbacks
. SmNeventSynchCallback
. SmGetRc
. SmGetEventId
. SmGetEventOptions
. SmNfocusGrantedCallback
. SmGetRc
. SmNfocusLostCallback
. SmGetRc
. SmNfocusStateCallback
. SmGetRc
. SmGetFocusChangeReason
. SmGetFocusState
. SmGetApplication
. SmNmicOffRequestedCallback
. SmGetRc
. SmNmicOnRequestedCallback
. SmGetRc
. SmNmicStateCallback
. SmGetRc
. SmGetMicState
. SmNplayMessageStatusCallback
. SmGetRc
. SmGetMsgName
. SmGetStatus
IBM ViaVoice SDK for Windows
Reply Structure Functions for Unsolicited Callbacks
. SmNplayUtteranceStatusCallback
. SmGetRc
. SmGetStatus
. SmGetUtteranceNumber
. SmNplayWordsStatusCallback
. SmGetRc
. SmGetStatus
. SmGetTags
. SmNrecognizedPhraseCallback
. SmGetRc
. SmGetAnnotations
. SmGetFirmWords
. SmGetVocabName
. SmGetPhraseState
. SmNrecognizedTextCallback
. SmGetRc
. SmGetFirmWords
. SmGetInfirmWords
. SmGetTimes
. SmNrecognizedWordCallback
. SmGetRc
. SmGetAlternates
. SmGetFirmWords
. SmGetTimes
IBM SMAPI Reference
Reply Message Structures and Callbacks
. SmNreportEngineErrorCallback
. SmGetRc
. SmGetMicState
. SmGetSeverity
. SmNutteranceCompletedCallback
. SmGetRc
. SmGetUtteranceNumber
IBM ViaVoice SDK for Windows
Chapter 6
Data Types
The following data types are used. They are listed in alphabetic order.
caddr_t
Pointer to character-aligned data.
typedef CHAR caddr_t;
SmArg
Speech argument list structure.
typedef struct _SmArg (CHAR name;
SmArgVal value;
) SmArg;
typedef SmArg SmArg;
Fields:
name
Name of speech argument.
value
Value of speech argument if size of argument is less than or equal to size of (long); otherwise, a
pointer to the speech argument value.
IBM SMAPI Reference
Data Types
SmArgVal
Value of speech argument if size of argument is less than or equal to size of (long); otherwise, a
pointer to the speech argument value.
typedef LONG SmArgVal;
SmHandler
Return value from callback-handler function.
typedef INT SmHandler;
IBM ViaVoice SDK for Windows
SM_ANNOTATION
SM_ANNOTATION
Annotation structure.
typedef struct _SM_ANNOTATION (LONG type;
UNION
{
LONG numeric;
CHAR *string;
VOID *other;
} annodata;
) SM_WORD;
typedef struct _SM_ANNOTATION SM_ANNOTATION;
Fields:
type
The type of annotation.
numeric
Return numeric annotations.
*string
Pointer to a structure in which to return string annotations.
*other
RESERVED.
IBM SMAPI Reference
Data Types
Sm_Msg
Pointer to message between speech recognition engine and application.
typedef VOID SM_MSG;
SM_VOCWORD
Vocabulary word-attribute structure.
typedef struct _SM_VOCWORD (LONG flags;
SHORT spelling_size;
CHAR *spelling;
) SM_VOCWORD;
typedef SM_VOCWORD SM_VOCWORD;
Fields:
flags
Reserved for internal use.
spelling_size
Number of chars in word spelling plus one for terminating NULL.
spelling
Word spelling.
IBM ViaVoice SDK for Windows
SM_WORD
SM_WORD
Word-attribute structure.
typedef struct _SM_WORD (LONG tag;
LONG flags;
LONG score;
SHORT spelling_size;
CHAR *spelling;
SHORT vocab_size;
CHAR *vocab;
) SM_WORD;
typedef SM_WORD SM_WORD;
Fields:
tag
Unique ID defined by speech recognition engine for this word.
flags
Formatting flags for words from predefined vocabularies.
score
Measure of word's probability. The score is relative and can vary from -100 to 100.
spelling_size
Number of chars in word spelling plus one for terminating NULL.
spelling
Word spelling.
vocab_size
Number of chars in vocabulary name plus one for terminating NULL.
vocab
Vocabulary name.
IBM SMAPI Reference
Data Types
IBM ViaVoice SDK for Windows
Chapter 7
SMAPI Attributes
This chapter lists and describes the SMAPI attributes. These attributes describe the current state of
your application's connection with the speech recognition engine (such as session type). You must set
several of the SMAPI attributes when you open and connect to a speech session. You set the values of
these attributes using SmSetArg or SmSesSetArg. When you set arguments, the engine creates an
internal structure to track the state of your session.
Refer to "Programming Tasks" in the SMAPI Developer’s Guide for more information on the use of
SmSetArg.
System Dependent Definition for Argument Lists
typedef long SmArgVal;
typedef struct {
char *name; /* name of the argument */
SmArgVal value; /* value of the argument */
} SmArg;
Argument Attribute List
Application Information Attributes
SmNapplicationName
The name of your speech-aware application. The speech recognition engine will use this attribute
to identify your application to other speech-aware applications.
IBM SMAPI Reference
SMAPI Attributes
Requested Services
SmNresetServices
Set to true to request that the type of session your application has connected to the speech
recognition engine be reset.
SmNdatabase
Set to true to request a database session with the engine.
SmNrecognize
Set to true to request a recognition session with the engine.
Options Flags
SmNdiscardSessionData
Set to true to discard the engine's temporary directory at session close.
SmNdiscardSessionAdaptation
Set to true to discard language model cache updates.
SmNSaveSessionData
Set to true to save the engine's temporary directory at session close.
SmNSaveSessionAdaptation
Set to true to merge the language model updates into persistent storage.
IBM ViaVoice SDK for Windows
Window Handle
SmNwindowHandle
Set to the window handle in your application that will receive all speech-related messages.
User Definition Arguments
SmNaudioHost
Used to initialize a recognition session. It can be set to use default values. Refer to "Overview of
the Custom Audio DLL's" in the SMAPI Developer's Guide for more information.
SmNconnectID
Used to initialize a recognition session. It can be set to use default values. Refer to "Establishing a
Speech Session" in the SMAPI Developer's Guide for more information.
SmNenrollID
Used to initialize a recognition session. It can be set to use default values. Refer to "Establishing a
Speech Session" in the SMAPI Developer's Guide for more information.
SmNnavigator
Used to define a session as the Navigator session. Refer to "Navigator Session" in the SMAPI
Developer's Guide for more information.
SmNtask
Used to initialize a recognition session. It can be set to use default values. Refer to "Establishing a
Speech Session" in the SMAPI Developer's Guide for more information.
IBM SMAPI Reference
SMAPI Attributes
SmNuserID
Used to initialize a recognition session. It can be set to use default values. Refer to "Establishing a
Speech Session" in the SMAPI Developer's Guide for more information.
IBM ViaVoice SDK for Windows
Chapter 8 DMAPI Overview
This chapter describes the format of the Dictation Macro (DMAPI) function calls that are presented in
Chapter 9. "DMAPI Function Calls". It also lists the calls that comprise DMAPI.
Format of the Function Call Descriptions
The description of each function call contains the following information:
Function Name
The name of the function call.
Purpose
The purpose and description of the function call.
Syntax
The syntax of the function as declared in DMAPI.H.
Parameters
Definitions of the parameters.
Return Values
Return values that are set by DMAPI.
For detailed descriptions of DMAPI errors, see “DMAPI Return Codes and Messages” on page 423.
IBM SMAPI Reference
DMAPI Overview
DMAPI Function Calls
The following section lists all of the DMAPI function calls.
. DmClose
. DmFlushEx
. DmFreeMacro
. DmFreeMacroEx
. DmFreeNames
. DmGetGroupsOnPage
. DmGetLastError
. DmGetKey
. DmGetKeyGroup
. DmGetKeyGroupOption
. DmGetKeyGroupOptionSelection
. DmGetLastError
. DmGetMacro
. DmGetMacroEx
. DmGetNumberOfGroups
. DmGetNumberOfOptions
. DmGetNumberOfSelections
. DmGetTemplate
. DmIsNumberFlagged
. DmKeywordFromType
. DmOpen
. DmQueryDelimiters
. DmQueryMacroNames
IBM ViaVoice SDK for Windows
DMAPI Function Calls
. DmQueryTemplateNames
. DmSetAndStoreKey
. DmSetKey
. DmStartMacroEditor
. DmStoreKey
. DmTypeFromKeyword
. DmUpdate
IBM SMAPI Reference
DMAPI Overview
IBM ViaVoice SDK for Windows
Chapter 9 DMAPI Function Calls
This chapter lists and describes the Dictation Macro API (DMAPI) function calls.
DmClose
Purpose
DmClose closes dictation macros for the specified user, domain, and language. It also frees
internally-allocated resources.
Syntax
unsigned long DmClose (DMHANDLE hmac);
Parameters
hmac
input - The DMAPI handle for the set of macros to be closed.
Return Values
DM_ERR_INVALID_HANDLE
DM_ERR_OK
IBM SMAPI Reference
DMAPI Function Calls
DmFlushEx
Purpose
DmFlushEx makes the number filter firm up on stacked data.
Syntax
unsigned long DmFlushEx (DMHANDLE hmac, unsigned short uExpand,
PDM_MACRO_STRUCT *pmac, unsigned long *num);
Parameters
hmac
input - A macro handle.
uExpand
input - One of the following flags:
DM_EXPAND_NONE - No expansion, just returns the text as it is stored.
DM_EXPAND_NORMAL -Expands the macro and all embedded macros with imm_expand set
If the macro itself is a delayed macro, the text will contain the macro name in the form
<MACRO macroname>.
DM_EXPAND_FULL -Expands the macro and all embedded macros no matter how the
imm_expand flags are set.
pmac
output -A pointer to the macro definition of the word was found or NULL in case of error. If
NULL is returned, the return code gives information about the type of error. Use DmFreeMacro
to free memory used by pointers returned by this function.
num
output -Number of pmac structures returned.
Return Values
DM_ERR_OK
DM_ERR_MALLOC
IBM ViaVoice SDK for Windows
DmFreeMacro
DmFreeMacro
Purpose
DmFreeMacro frees memory associated with a macro or template previously obtained by
DmGetMacro or DmGetTemplate.
Syntax
void DmFreeMacro (PDM_MACRO_STRUCT macro);
Parameters
macro
input - A pointer to the macro definition.
Return Values
None
IBM SMAPI Reference
DMAPI Function Calls
DmFreeMacroEx
Purpose
DmFreeMacroEx frees memory of a macro or template previously obtained by DmGetMacro or
DmGetTemplate.
Syntax
void DmFreeMacroEx (PDM_MACRO_STRUCT macro, unsigned long num);
Parameters
macro
input - A pointer to the macro definition.
num
input - Number of macros in the macro. (See DmGetMacroEx)
Return Values
None
IBM ViaVoice SDK for Windows
DmFreeNames
DmFreeNames
Purpose
DmFreeNames frees memory associated with the fields previously allocated by
DmQueryMacroNames or DmQueryTemplateNames.
Syntax
void DmFreeNames (unsigned short number, char **field);
Parameters
number
input - The number of list entries.
field
input - A pointer to a field of strings that contains the names of macros or templates.
Return Values
None
IBM SMAPI Reference
DMAPI Function Calls
DmGetGroupsOnPage
Purpose
DmGetGroupsOnPage returns the number of groups to display per options page.
Syntax
unsigned long DmGetGroupsOnPage (DMHANDLE hmac, int *page1, int *page2,
int *page3);
Parameters
hmac
input - A macro handle.
page 1 to page 3
output - The number of groups to display on the Options page n, if all are 0, do not show an options
panel at all.
Return Values
DM_ERR_OK
IBM ViaVoice SDK for Windows
DmGetKey
DmGetKey
Purpose
DmGetKey queries the number filter for this value to a key.
Syntax
unsigned long DmGetKey (DMHANDLE hmac, char *key, char **value,
unsigned long *num);
Parameters
hmac
input - The macro handle.
key
input - The key.
value
output - The value.
num
output - The number of values returned.
Return Values
DM_ERR_OK
DM_ERR_MALLOC
DM_ERR_INVALID_KEYWORD
IBM SMAPI Reference
DMAPI Function Calls
DmGetKeyGroup
Purpose
DmGetKeyGroup returns the string to display for a given group number.
Syntax
unsigned long DmGetKeyGroup (DMHANDLE hmac, int group,
char **display_string);
Parameters
hmac
input - The macro handle.
group
input - The group number for which the display_string should be returned.
display_string
output -The ANSI string to display on the Options panel.
Return Values
DM_ERR_OK
DM_ERR_INVALID_KEYWORD
IBM ViaVoice SDK for Windows
DmGetKeyGroupOption
DmGetKeyGroupOption
Purpose
DmGetKeyGroupOption returns the string to display for a given group number/option.
Syntax
unsigned long DmGetKeyGroupOption (DMHANDLE hmac, int group, int option,
char **display_string);
Parameters
hmac
input - The macro handle.
group
input - The group number for which the display_string should be returned.
option
input - The option number for which the display_string should be returned.
display_string
output -The ANSI string to display on the Options panel.
Return Values
DM_ERR_OK
DM_ERR_INVALID_KEYWORD
IBM SMAPI Reference
DMAPI Function Calls
DmGetKeyGroupOptionSelection
Purpose
DmGetKeyGroupOptionSelection returns the string to display for a given group number/option/
selection.
Syntax
unsigned long DmGetKeyGroupOptionSelection (DMHANDLE hmac, int group,
int option, int selection, char **display_string);
Parameters
hmac
input - The macro handle.
group
input - The group number for which the display_string should be returned.
option
input - The option number for which the display_string should be returned.
selection
input - The selection number for which the display_string should be returned.
display_string
output -The ANSI string to display on the Options panel.
Return Values
DM_ERR_OK
DM_ERR_INVALID_KEYWORD
IBM ViaVoice SDK for Windows
DmGetLastError
DmGetLastError
Purpose
DmGetLastError returns additional information about the last error. This call does not change the
internally-stored error information.
DmGetLastError uses a DMERROR structure which contains the following information:
errbuf->errno
The DM_ERR_... value of the last error.
errbuf->string
Additional information about the last error:
DM_ERR_ACT_FILE_PARSE line number
DM_ERR_BAD_EXE_FORMAT file name
DM_ERR_DUPLICATE_MACRO macro name
DM_ERR_EACCESS file name
DM_ERR_EBADF file name
DM_ERR_EMFILE file name
DM_ERR_ENOENT file name
DM_ERR_EXPDLL_LOAD_FAILED DLL name
DM_ERR_EXPDLL_QUERYFUN_FAILED function name
DM_ERR_FILE_READ file name
DM_ERR_INVALID_DOMAIN domain name
DM_ERR_INVALID_LANGUAGE language code
DM_ERR_INVALID_MACRORELEASE release number
DM_ERR_INVALID_MACROVERSION version number
DM_ERR_INVALID_USERID user ID
DM_ERR_LOAD_RESOURCE_DLL name of DLL
DM_ERR_MACRO_NOT_FOUND macro name
DM_ERR_TEMPLATE_NOT_FOUND template name
DM_ERR_UNDEFINED file name
Syntax
void DmGetLastError (PDMERROR errbuf);
Parameters
errbuf
IBM SMAPI Reference
DMAPI Function Calls
output - A pointer to a DMERROR structure.
Return Values
None
IBM ViaVoice SDK for Windows
DmGetMacro
DmGetMacro
Purpose
DmGetMacro gets a macro definition from the current set of macros.
Syntax
unsigned long DmGetMacro(DMHANDLE hmac, char *word, unsigned short uExpand,
PDM_MACRO_STRUCT *pmac);
Parameters
hmac
input - The macro handle.
word
input -The name of the macro.
uExpand
input - The type of expansion to be performed, which can be one of the following:
DM_EXPAND_NONE - The macro should not be expanded, only the text as it is stored will be
returned.
DM_EXPAND_NORMAL -The macro and all embedded macros with imm_expand set to
TRUE will be expanded. Delayed macros will not be expanded. If the macro itself is a delayed
macro, the text will contain the macro name in the form <MACRO macroname>.
DM_EXPAND_FULL - The macro and all embedded macros (regardless of the value of
imm_expand) will be expanded.
pmac
output - If the word was found, a pointer to the macro definition; otherwise, it will be set to NULL.
If NULL is returned, the return code gives information about the type of error. Use DmFreeMacro
to free memory used by pointers returned by this function.
IBM SMAPI Reference
DMAPI Function Calls
Return Values
DM_ERR_EXPDLL_ERR
DM_ERR_EXPDLL_LOAD_FAILED
DM_ERR_EXPDLL_QUERYFUN_FAILED
DM_ERR_EXPDLL_TIMEOUT
DM_ERR_INVALID_HANDLE
DM_ERR_MACRO_NOT_FOUND
DM_ERR_MALLOC
DM_ERR_OK
DM_ERR_SYSTEM_PARM_LONG
IBM ViaVoice SDK for Windows
DmGetMacroEx
DmGetMacroEx
Purpose
DmGetMacroEx gets a macro definition from the current set of macros.
Syntax
unsigned long DmGetMacroEx (DMHANDLE hmac, char *word, char *soundslike,
unsigned long flags, unsigned long tag, unsigned short uExpand,
PDM_MACRO_STRUCT *pmac);
Parameters
hmac
input - The macro handle.
word
input -The name of the macro.
soundslike
input - The soundslike field for spellout function.
flags
input -The number and other flags.
uExpand
input - The type of expansion to be performed, which can be one of the following:
DM_EXPAND_NONE - The macro should not be expanded, only the text as it is stored will
be returned.
DM_EXPAND_NORMAL -The macro and all embedded macros with imm_expand set to
TRUE will be expanded. Delayed macros will not be expanded. If the macro itself is a delayed
macro, the text will contain the macro name in the form <MACRO macroname>.
DM_EXPAND_FULL - The macro and all embedded macros (regardless of the value of
imm_expand) will be expanded.
pmac
output - If the word was found, a pointer to the macro definition; otherwise, it will be set to NULL.
If NULL is returned, the return code gives information about the type of error. Use DmFreeMacro
to free memory used by pointers returned by this function.
IBM SMAPI Reference
DMAPI Function Calls
Return Values
DM_ERR_EXPDLL_ERR
DM_ERR_EXPDLL_LOAD_FAILED
DM_ERR_EXPDLL_QUERYFUN_FAILED
DM_ERR_EXPDLL_TIMEOUT
DM_ERR_INVALID_HANDLE
DM_ERR_MACRO_NOT_FOUND
DM_ERR_MALLOC
DM_ERR_OK
DM_ERR_SYSTEM_PARM_LONG
IBM ViaVoice SDK for Windows
DmGetNumberOfGroups
DmGetNumberOfGroups
Purpose
DmGetNumberOfGroups returns the number of groups for display in the Options panel.
Syntax
unsigned long DmGetNumberOfGroups (DMHANDLE hmac);
Parameters
hmac
input - The macro handle.
Return Values
0 - When no groups are found.
>0 - Represents the number of groups found.
IBM SMAPI Reference
DMAPI Function Calls
DmGetNumberOfOptions
Purpose
DmGetNumberOfOptions returns the number of options for display in the Options panel.
Syntax
unsigned long DmGetNumberOfOptions (DMHANDLE hmac, int group);
Parameters
hmac
input - The macro handle.
group
input - The group number for which the options should be returned.
Return Values
0 - When no options are found.
>0 - Represents the number of options found.
IBM ViaVoice SDK for Windows
DmGetNumberOfSelections
DmGetNumberOfSelections
Purpose
DmGetNumberOfSelections returns the number of selections for display in the Options panel.
Syntax
unsigned long DmGetNumberOfSelections (DMHANDLE hmac, int group,
int option);
Parameters
hmac
input - The macro handle.
group
input -The group number for which the selection should be returned.
option
input - The option number for which the selection should be returned.
Return Values
0 - When no selections are found.
>0 - Represents the number of selections found.
IBM SMAPI Reference
DMAPI Function Calls
DmGetTemplate
Purpose
DmGetTemplate gets a template definition from the current set of templates.
Syntax
unsigned long DmGetTemplate (DMHANDLE hmac, char *word,
unsigned short uExpand, PDM_MACRO_STRUCT *pmac);
Parameters
hmac
Input -The DMAPI handle for the current set of templates.
word
input -The name of the template.
uExpand
input - The type of expansion to be performed, which can be one of the following:
DM_EXPAND_NONE - The template should not be expanded, only the text as it stored will
be returned.
DM_EXPAND_NORMAL -The template and all embedded macros with imm_expand set
to TRUE will be expanded. Delayed macros will not be expanded.
DM_EXPAND_FULL -The template and all embedded macros (regardless of the value of
imm_expand) will be expanded.
pmac
output - If the word was found, a pointer to the template definition; otherwise, it will be set to
NULL. If NULL is returned, the return code gives information about the type of error. Use
DmFreeMacro to free memory used by pointers returned by this function.
IBM ViaVoice SDK for Windows
DmGetTemplate
Return Values
DM_ERR_EXPDLL_ERR
DM_ERR_EXPDLL_LOAD_FAILED
DM_ERR_EXPDLL_QUERYFUN_FAILED
DM_ERR_EXPDLL_TIMEOUT
DM_ERR_INVALID_HANDLE
DM_ERR_MALLOC
DM_ERR_OK
DM_ERR_SYSTEM_PARM_LONG
DM_ERR_TEMPLATE_NOT_FOUND
IBM SMAPI Reference
DMAPI Function Calls
DmIsNumberFlagged
Purpose
DmIsNumberFlagged returns !=0 if the flag is a number flag.
Syntax
unsigned long DmIsNumberFlagged (unsigned long flags);
Parameters
flags
input - The flag returned from the speech engine.
Return Values
0 - Not flagged as a number
>0 - Bits 0-11 contain the number flags
IBM ViaVoice SDK for Windows
DmKeywordFromType
DmKeywordFromType
Purpose
DmKeywordFromType gets the keywords used by the Dictation Macro Editor.
Syntax
unsigned long DmKeyWordFromType (DMHANDLE dmac, unsigned short type,
char **keyword);
Parameters
dmac
input - The macro handle.
type
input - The type from which to get the keyword, which can be one of the KEYBOARD_xx found
below:
KEYWORD_INVALID 0
KEYWORD_NONE 1
KEYWORD_DAYOFWEEK 2
KEYWORD_DATE 3
KEYWORD_TIME 4
KEYWORD_DAY 5
KEYWORD_DAYORDINAL 6
KEYWORD_MONTHOFYEAR 7
KEYWORD_MONTHSHORT 8
KEYWORD_MONTH 9
KEYWORD_YEAR 10
KEYWORD_YEARSHORT 11
KEYWORD_MSGSTRING 14
KEYWORD_DLLCALL 15
KEYWORD_DLLSTRING 16
KEYWORD_SYSTEM 17
KEYWORD_MACRO 18
keyword
The keyword of the input type. The language of the keyword depends on the language associated
with the macro handle.
IBM SMAPI Reference
DMAPI Function Calls
Return Values
DM_ERR_INVALID_KEYTYPE
DM_ERR_OK
IBM ViaVoice SDK for Windows
DmOpen
DmOpen
Purpose
DmOpen opens dictation macros for the specified user, domain, and language.
Syntax
unsigned long DmOpen (void *init, char *username, char *domain, char *lang,
PDMHANDLE hmac);
Parameters
init
input - This parameter is RESERVED and must be set to NULL.
username
input - The user name (5-char. code) for which the macros should be initialized.
domain
input - The domain (5-char. code) for which the macros should be initialized.
lang
input - The language (5-char. code) for which the macros should be initialized. This code should be
retrieved from the speech recognition engine.
hmac
output - The Dictation Macro Editor specific handle which is needed for further calls for this set of
macros.
Return Values
DM_ERR_DUPLICATE_MACRO
DM_ERR_EACCESS
DM_ERR_EBADF
DM_ERR_EMFILE
DM_ERR_ENOENT
DM_ERR_INVALID_DOMAIN
DM_ERR_INVALID_LANGUAGE
DM_ERR_INVALID_MACRO
DM_ERR_INVALID_MACROFILE
DM_ERR_INVALID_USERID
IBM SMAPI Reference
DMAPI Function Calls
DM_ERR_LOAD_RESOURCE_DLL
DM_ERR_MALLOC
DM_ERR_NOTIFY_EXCEEDED
DM_ERR_OK
DM_ERR_UNDEFINED
IBM ViaVoice SDK for Windows
DmQueryDelimiters
DmQueryDelimiters
Purpose
DmQueryDelimiters requests the keyword and template field delimiters used by the Dictation
Macro Editor.
Syntax
void DmQueryDelimiters (unsigned char *FieldStart,
unsigned char *FieldEnd, unsigned char *KeywordStart,
unsigned char *KeywordEnd, unsigned char *EscapeChar);
Parameters
FieldStart
output - The character which indicates the start of a field.
FieldEnd
output - The character which indicates the end of a field.
KeywordStart
output - The character which indicates the start of a keyword.
KeywordEnd
output - The character which indicates the end of a keyword.
EscapeChar
output - The character which indicates the escape character.
Return Values
None
IBM SMAPI Reference
DMAPI Function Calls
DmQueryMacroNames
Purpose
DmQueryMacroNames requests a list of the names of all available dictation macros.
Use DmFreeNames to free memory used by the field returned by this function.
Syntax
unsigned long DmQueryMacroNames (DMHANDLE hmac, unsigned short *number,
char ***names);
Parameters
hmac
input - The macro handle.
number
output - The number of entries in the list.
names
output - A pointer to a field of string pointers containing the names of the macros. If the number of
macros is 0, this pointer is set to NULL.
Return Values
DM_ERR_INVALID_HANDLE
DM_ERR_MALLOC
DM_ERR_OK
IBM ViaVoice SDK for Windows
DmQueryTemplateNames
DmQueryTemplateNames
Purpose
DmQueryTemplateNames requests a list of the names of all available dictation templates.
Use DmFreeNames to free memory used by the field returned by this function.
Syntax
unsigned long DmQueryTemplateNames(DMHANDLE hmac, unsigned short * number,
char ***names);
Parameters
hmac
input - The handle for the current set of templates.
number
output - The number of entries in the list.
names
output - A pointer to a field of string pointers containing the names of the templates. If the number
of templates is 0, this pointer is set to NULL.
Return Values
DM_ERR_INVALID_HANDLE
DM_ERR_MALLOC
DM_ERR_OK
IBM SMAPI Reference
DMAPI Function Calls
DmQuerySetAndStoreKey
Purpose
DmQuerySetAndStoreKey sets the current session and stores for future use the given value to the
given key.
Syntax
unsigned long DmQuerySetAndStoreKey(DMHANDLE hmac, char *key, char *value);
Parameters
key
input -The number dictation key.
value
input - The value associated to the key.
Return Values
DM_ERR_INVALID_KEYWORD
DM_ERR_OK
IBM ViaVoice SDK for Windows
DmSetKey
DmSetKey
Purpose
DmSetKey sets the key for the current session only.
Syntax
unsigned long DmSetKey (DMHANDLE hmac, char *key, char *value);
Parameters
hmac
input - The macro handle.
key
input -The number dictation key.
value
input - The value associated to the key.
Return Values
DM_ERR_INVALID_KEYWORD
DM_ERR_OK
IBM SMAPI Reference
DMAPI Function Calls
DmStartMacroEditor
Purpose
DmStartMacroEditor starts the Dictation Macro Editor. If the Dictation Macro Editor is already
running, DmStartMacroEditor switches focus to the already-running Dictation Macro Editor.
Syntax
unsigned long DmStartMacroEditor (char *lang);
Parameters
lang
input -The language for which the Dictation Macro Editor should be started.
Return Values
DM_ERR_BAD_EXE_FORMAT
DM_ERR_ENOENT
DM_ERR_OK
DM_ERR_OUT_OF_SYSTEM_RES
IBM ViaVoice SDK for Windows
DmStoreKey
DmStoreKey
Purpose
DmStoreKey stores the given value to the given key for future use.
Syntax
unsigned long DmStoreKey (DMHANDLE hmac, char *key, char *value);
Parameters
hmac
input - The macro handle.
key
input -The number dictation key.
value
input - The value associated to the key.
Return Values
DM_ERR_INVALID_KEYWORD
DM_ERR_OK
IBM SMAPI Reference
DMAPI Function Calls
DmTypeFromKeyword
Purpose
DmTypeFromKeyword returns the type constant of the specified keyword.
Syntax
unsigned long DmTypeFromKeyword (DMHANDLE dmac, char *keyword,
unsigned short *type);
Parameters
dmac
input - The handle for the current set of macros.
keyword
input - The keyword from which to get the type. The keyword depends on the language associated
with the macro handle.
type
output - The type of the keyword, which can be one of the following:
KEYWORD_INVALID 0
KEYWORD_NONE 1
KEYWORD_DAYOFWEEK 2
KEYWORD_DATE 3
KEYWORD_TIME 4
KEYWORD_DAY 5
KEYWORD_DAYORDINAL 6
KEYWORD_MONTHOFYEAR 7
KEYWORD_MONTHSHORT 8
KEYWORD_MONTH 9
KEYWORD_YEAR 10
KEYWORD_YEARSHORT 11
KEYWORD_MSGSTRING 14
KEYWORD_DLLCALL 15
KEYWORD_DLLSTRING 16
KEYWORD_SYSTEM 17
KEYWORD_MACRO 18
IBM ViaVoice SDK for Windows
DmTypeFromKeyword
Return Values
DM_ERR_INVALID_KEYWORD
DM_ERR_OK
IBM SMAPI Reference
DMAPI Function Calls
DmUpdate
Purpose
DmUpdate updates the loaded macro database with all changes that have been made to macros or
templates since the last time DmUpdate was called.
Syntax
unsigned long DmUpdate (DMHANDLE hmac, int reserved1, int reserved2);
Parameters
hmac
input - The DME handle for the macro database to be updated.
reserved1
input - RESERVED parameter - must be set to 0.
reserved2
input - RESERVED parameter - must be set to 0.
Return Values
DM_ERR_DUPLICATE_MACRO
DM_ERR_EACCESS
DM_ERR_EBADF
DM_ERR_EMFILE
DM_ERR_ENOENT
DM_ERR_INVALID_HANDLE
DM_ERR_INVALID_MACRO
DM_ERR_INVALID_MACROFILE
DM_ERR_NOUPDATE
DM_ERR_OK
DM_ERR_UNDEFINED
IBM ViaVoice SDK for Windows
Chapter 10
Data Types
The following data types are used by DMAPI. They are listed in alphabetic order.
DMERROR
Error structure returned by DmGetLastError.
typedef struct
{
ULONG errorcode;
UCHAR string[DM_MAX_ERROR_LEN+1];
} DMERROR, *PDMERROR;
Fields:
errorcode
DMAPI error code.
string
Additional information based on error code.
IBM SMAPI Reference
Data Types
DM_MACRO_STRUCT
Macro structure.
DM_MACRO_STRUCT is used for both "normal" macro definitions and templates. For macros,
numfield is always set to 0 and fields is always NULL. For templates, numfield is greater than 0
and fields points to the field definition(s). Additionally, imm_expand is ignored for templates,
since templates are always expanded immediately.
typedef struct
{
ULONG type;
PCHAR name;
PCHAR text;
PCHAR desc;
CHAR domain[MAX_DOMAIN_LEN];
ULONG joinleft;
ULONG joinright;
ULONG joindigit;
ULONG casing;
ULONG imm_expand;
ULONG numfield;
PDM_TEMPLATE_FIELD *fields;
ULONG affect;
} DM_MACRO_STRUCT, *PDM_MACRO_STRUCT;
Fields:
type
Type of macro (DM_MACTYPE_MACRO or DM_MACTYPE_TEMPLATE)
name
Word to activate macro.
text
Macro text.
IBM ViaVoice SDK for Windows
DM_MACRO_STRUCT
desc
Template description.
domain
Domain name (length is 0 if this is a global macro).
joinleft
Formatting flag: Join to previous word.
joinright
Formatting flag: Join to next word.
joindigit
Formatting flag: Join digits.
casing
Casing of next word (DM_CASE_NONE, DM_CASE_CAPITAL, DM_CASE_UPPERCASE,
DM_CASE_LOWERCASE)
imm_expand
Expand immediately (always TRUE for templates).
numfield
Number of fields (only valid for templates).
fields
Template fields.
affect
TRUE for macros that should be affected by macros (such as "italian 1").
IBM SMAPI Reference
Data Types
DM_TEMPLATE_FIELD
Template field structure.
typedef struct
{
ULONG type;
PCHAR prompt;
PCHAR defaulttext;
ULONG position;
ULONG numsel;
PCHAR *selword;
} DM_TEMPLATE_FIELD, *PDM_TEMPLATE_FIELD;
Fields:
type
Type of field (DM_FLDTYP_TEXT, DM_FLDTYP_SPELL, DM_FLDTYP_DIGIT,
DM_FLDTYP_SELECTION).
prompt
Prompt text for field.
defaulttext
Default text of the field.
position
Position within text.
numsel
Number of selection words if type=DM_FLDTYP_SELECTION.
selword
Field of selection words.
IBM ViaVoice SDK for Windows
Chapter 11 SMAPI Grammar Compiler API
Overview
This chapter describes the format of the Grammar Compiler API function calls that are presented in
Chapter 12. "Grammar Compiler API Function Calls". It also lists the calls that are provided by the
Grammar Compiler DLL (VTBNFC31.DLL).
Format of the Function Call Descriptions
The description of each function call contains the following information:
Function Name
The name of the function call.
Purpose
The purpose and description of the function call.
Syntax
The syntax of the function as declared in VTBNFC.H.
Parameters
Definitions of the parameters.
Return Values
Return values that are set by the Grammar Compiler DLL.
IBM SMAPI Reference
SMAPI Grammar Compiler API Overview
Grammar Compiler API Function Calls
The following function calls are provided as part of the Grammar Compiler DLL:
. VtAddArg
. VtCompileGrammar
. VtGetMessage
. VtSetArg
IBM ViaVoice SDK for Windows
Chapter 12 SMAPI Grammar Compiler API
Function Calls
This chapter lists and describes the SMAPI Grammar Compiler API function calls.
VtAddArg
Purpose
VtAddArg is a macro that adds an argument with the specified attributes to the end of a VtArg
structure. This function sets the components of the arg parameter. The pointer to arg or to a list of
similarly created arguments can then be passed to VtCompileGrammar. VtAddArg increments
an index to point to the last argument in the argument list.
For further information on using the VtArg data structure, see “Data Types” on page 363.
Syntax
void VtAddArg (VtArg arg, long index, char *name, long value);
Parameters
arg
input - The argument.
index
output -The index into the argument structure. VtAddArg increments the index by one.
name
input -The name of the attribute.
value
input - The value of the attribute.
Return Values
None.
IBM SMAPI Reference
SMAPI Grammar Compiler API Function Calls
VtCompileGrammar
Purpose
VtCompileGrammar compiles a BNF file and produces an FSG using the specified parameters.
The Grammar Compiler parameters are provided by setting up an argument list (VtArg). For more
information on creating and using the VtArg structure, see “Data Types” on page 363.
Syntax
int VtCompileGrammar (int nargs, VtArg *args);
Parameters
nargs
input -The number of arguments in the argument list.
args
input - The pointer to an argument structure that indicates the Grammar Compiler parameters to be
used.
Return Values
- Successful.
Other - Use VtGetMessage to obtain more detailed error information.
IBM ViaVoice SDK for Windows
VtAddArg
VtGetMessage
Purpose
VtGetMessage returns a pointer to a message string that describes the errors encountered during
the last VtCompileGrammar call that returned a non-zero error code.
The messages returned by VtGetMessage are exactly the same messages (errors and warnings)
that are generated by the Grammar Compiler and can be used to determine the cause of the errors
and appropriate action to be taken by the application.
Syntax
int VtGetMessage(char **message);
Parameters
message
input - The pointer to a character string which holds the error information.
Return Values
None.
IBM SMAPI Reference
SMAPI Grammar Compiler API Function Calls
VtGetTranslation
Purpose
VtCompileGrammar gets a translation for a phrase contained in the “words” parameter
according to the FSG file referred to by the “fsg” parameter.
Syntax
int VtGetTranslation (void *fsg, char **words, char **translation);
Parameters
fsg
input - The pointer to an FST file loaded by VtLoadFSG.
words
input - The pointer to a NULL-terminated array of pointers to words that you supply.
translation
input - The pointer to a character pointer that will hold the translation returned by
VtGetTranslation.
Return Values
- Successful.
Other - Use VtGetMessage to obtain more detailed error information.
IBM ViaVoice SDK for Windows
VtAddArg
Example
char *name = // name of your .fsg file
void *fsg;
int rc = VtLoadFSG(name, &fsg);
char *translation;
int n = // number of words
char **words = new char*[n+1];
for (int i=0; i<n; i++)
words = // assign the ith word
words[n] = NULL;
rc = VtGetTranslation(fsg, words, &translation);
printf("translation is '%s'/n", translation);
rc = VtUnloadFSG(fsg);
IBM SMAPI Reference
SMAPI Grammar Compiler API Function Calls
VtLoadFSG
Purpose
VtLoadFSG loads an FSG or FST file produced by the command-line compiler VTBNFC.EXE,
or by the compiler API VtCompileGrammar. After loading a grammar with VtLoadFSG, you
may use VtGetTranslation to get translations for recognized phrases returned by the ViaVoice
recognition engine.
Syntax
int VtLoadFSG (char *name, voice **fsg);
Parameters
name
input - The file name of the FST or FSG file you want to load.
fsg
input - The pointer to a void* to receive the loaded grammar.
Return Values
- Successful.
Other - Use VtGetMessage to obtain more detailed error information.
IBM ViaVoice SDK for Windows
VtAddArg
VtSethArg
Purpose
VtSetArg is a macro that fills a VtArg structure with the specified attributes.
This function sets the components of the arg parameter. The pointer to arg or to a list of similarly
created arguments can then be passed to VtCompileGrammar.
For further information on using the VtArg data type, see “Data Types” on page 363.
Syntax
void VtSetArg (VtArg arg, char *name, long value);
Parameters
arg
input - The argument.
name
input -The name of the attribute.
value
input - The value of the attribute.
Return Values
None.
IBM SMAPI Reference
SMAPI Grammar Compiler API Function Calls
VtUnloadFSG
Purpose
VtUnloadFSG unloads an FSG or FST file that was previously loaded by VtLoadFSG.
Syntax
void VtUnloadFSG (void *fsg);
Parameters
fsg
input - The pointer to an FST loaded by VtLoadFSG.
Return Values
- Successful.
Other - Use VtGetMessage to obtain more detailed error information.
IBM ViaVoice SDK for Windows
Chapter 13
Data Types
The following data type is used by the SMAPI Grammar Compiler APIs:
VtArg
Argument structure for VtCompileGrammar.
typedef struct {
char *name;
long value;
} VtArg;
Fields:
name
Name of a VtCompileGrammar argument.
value
Value of the VtCompileGrammar argument if the size of the argument is less than or equal to the
size of (long); otherwise, a pointer to the VtCompileGrammar argument value.
VtArg is analogous to SmArg in SMAPI.; therefore, VtSetArg is analogous to SmSetArg.
Possible arguments for VtSetArg (and VtAddArg) are:
VtNbnfFile -The input BNF file.
VtfsgFile - The output FSG file. This is equivalent to -o on the command line.
VtNfsgDirectory -The output directory for multiple roots. This is equivalent to the -d
parameter on the command line.
VtNequalizeArcProbabilities - The non-uniform probability computation. When set to 1, arc
probabilities are equalized. (This is the default if not specified.) When set to 0, arc
probabilities are not equalized. This argument is equivalent to the -n parameter on the
command line.
IBM SMAPI Reference
Data Types
VtNfsgFlags -SmDefineGrammar flags. The possible flag values are:
SM_PHRASE_ALLOW_SILENCES, SM_PHRASE_SHOW_SILENCES,
SM_PHRASE_NO_SILENCES, SM_PHRASE_ALLOW_INSERTIONS,
SM_PHRASE_SHOW_INSERTIONS, SM_PHRASE_NO_INSERTIONS.
VtNtrMode is specified with a parameter value of 1. It is used to compile grammars that
contain translations to produce an FST file for use by VtLoadFSG. It is equivalent to the “-tr”
for the VTBNFC.EXE command-line compiler.
VtNenMode is specified with a parameter value of 1. It is used to compile grammars that
contain translations to produce an FSG file for use by the engine (SmDefineGrammar). It is
equivalent to the “-en” for the VTBNFC.EXE command-line compiler.
Note:
For more information on command line parameters, refer to "Grammar Compiler" in the IBM
SMAPI Developer's Guide.
IBM ViaVoice SDK for Windows
The following example illustrates how to fill in a VtArg structure before calling VtCompileGrammar
and how to use VtGetMessage if the return from VtCompileGrammar is not equal to zero:
int n = 0;
VtArg args[10];
VtAddArg( args, n, VtNbnfFile, "mygrammar.bnf" );
VtAddArg( args, n, VtNfsgFlags, SM_PHRASE_SHOW_SILENCES |
SM_PHRASE_ALLOW_INSERTIONS);
// Additional parameters specified by additional VtAddArg calls
int rc = VtCompileGrammar( n, args );
if ( rc !=0 )
{
char *message;
VtGetMessage( &message );
printf( message );
}
Figure 1. Using VtAddArg, VtCompileGrammar, and VtGetMessage
IBM SMAPI Reference
Data Types
IBM ViaVoice SDK for Windows
Chapter 14 VtGeneratePronunciations
This chapter describes the VtGeneratePronunciations API, which is included with the ViaVoice SDK
to enable the unlimited vocabulary capability for SMAPI applications. VtGeneratePronunciations is
provided as a separate DLL (UVOCAB.DLL) which must be included with any application that uses
the function.
Note:
The unlimited vocabulary capability uses the SAPI interface to the text-to-speech engine. As a
result, SMAPI applications that incorporate the VtGeneratePronunciations call must also include
the Microsoft Speech API (SAPI) redistributable files for this function to work. These files are
available from Microsoft.
For more information on the unlimited vocabulary capability, refer to the SMAPI Developer's Guide.
VtGeneratePronunciations
Purpose
VtGeneratePronunciations adds pronunciations for words returned by SmDefineVocab and
SmDefineGrammar that do not have pronunciations in the engine. The baseform pronunciations
that VtGeneratePronuncation builds are obtained from the text-to-speech engine dictionaries,
and are placed in the engine's temporary pronunciation pools.
This function returns TRUE if pronunciations for all words in the list are added to the engine. It
returns FALSE if one or more words failed in phonetization or in being added to the engine. With a
return code of FALSE, an application can reissue SmDefineVocab or SmDefineGrammar to
obtain the list of words that could not be added, if required.
The following restriction applies when calling VtGeneratePronunciations:
. The speech recognition engine must be halted.
IBM SMAPI Reference
VtGeneratePronunciations
Notes:
1.
SmDefineGrammar always fails on one or more missing words. SmDefineVocab will
succeed, even if all words are missing. An application will need to undefine a dynamic
vocabulary before reissuing the SmDefineVocab call to find the list of failed phonetizations.
2.
Users of this function should adhere to the rules and restrictions that COM places on outgoing
calls while handling messages from another process. In particular, this function should not be
called from a message handler while handling a SendMessage that was generated by another
process.
Syntax
BOOL VtGeneratePronunciations (SmSesId session_id, unsigned long nmissing,
SM_VOCWORD *missing);
Parameters
session_id
input - An open SMAPI session ID, returned by SmSesOpen.
Note: Applications using SmOpen do not have explicit access to the session ID; in this case,
specify a default value of 0.
nmissing
input - The number of words missing pronunciations, returned by SmGetVocWords. Limited to
SM_MAX_VOCWORDS.
missing
input - The pointer to an array of SM_VOCWORDS, returned by SmGetVocWords.
Return Values
TRUE -If all words are added to the engine.
FALSE - If one or more words failed in phonetization or in being added to the engine.
IBM ViaVoice SDK for Windows
Appendix A SMAPI Return Codes, Messages,
and Message Types
The return codes and messages, defined in SMRC.H, and the message types, defined in SMCOMM.H,
are generated by the SMAPI.
SMAPI Return Codes and Messages
The following list contains the return code values in numeric order for the SMAPI.
-28 SM_API_RC_MIN_NAMES
-27 SM_RC_ATTACH_MUTEX_SEM_FAILED
-26 SM_RC_CREATE_MUTEX_SEM_FAILED
-25 SM_RC_OPEN_QUEUE_FAILED
-24 SM_RC_SUB_UNSET_ERROR
-23 SM_RC_CLOSE_EVENT_SEM_FAILED
-22 SM_RC_FREE_MEM_ERROR
-21 SM_RC_QUEUE_CLOSE_ERROR
-20 SM_RC_DEALLOCATING_SH_MEM
-19 SM_RC_ASSOC_EVENT_SEM_FAILED
-18 SM_RC_CREATE_EVENT_SEM_FAILED
-17 SM_RC_CREATE_MBOX_FAILED
-16 SM_RC_EALLBUSY
-15 SM_RC_ENOACCEPT
-14 SM_RC_EBADAPPNAME
-13 SM_RC_EALLOC
-12 SM_RC_ENOMEM
-11 SM_RC_EBADHANDLE
-10 SM_RC_ENOHANDLES
-9 SM_RC_EMSGSIZE
-8 SM_RC_EUNKMSG
-7 SM_RC_ETIMEOUT
IBM SMAPI Reference
-6 SM_RC_EUNEXP
-5 SM_RC_EINVAL
-4 SM_RC_ENOSERVER
-3 SM_RC_ENOCONN
-2 SM_RC_ENOMSG
-1 SM_RC_EAPIVERSION
0 SM_RC_OK
1 SM_RC_NOT_VALID_REQUEST
2 SM_RC_BAD_MODE
3 SM_RC_NOT_WHILE_MIC_ON
4 SM_RC_MIC_ALREADY_ON
5 SM_RC_MIC_ALREADY_OFF
6 SM_RC_MIC_ON_PENDING
7 SM_RC_MIC_OFF_PENDING
8 SM_RC_NOT_WHILE_PLAYING
10 SM_RC_BAD_AUDIO
11 SM_RC_RECORD_OPEN_ERROR
12 SM_RC_PLAY_OPEN_ERROR
13 SM_RC_AUDIO_IN_USE
14 SM_RC_BAD_AUDIO_PROTOCOL
15 SM_RC_AUDIO_TIMEOUT
16 SM_RC_AUDIO_DISCONNECTED
17 SM_RC_AUDIO_OVERRUN
18 SM_RC_AUDIO_FORCED_MIC_OFF
19 SM_RC_NO_MORE_AUDIO_FILES
20 SM_RC_BAD_AP
28 SM_API_RC_MAX_NAMES
30 SM_RC_BAD_DECO
40 SM_RC_BAD_ADDWORD
41 SM_RC_ADDED
42 SM_RC_NOT_ADDED
43 SM_RC_MULTIPLE_SPELLINGS
44 SM_RC_ILLEGAL_SPELLING
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
45
SM_RC_ILLEGAL_SPOKENLIKE
46
SM_RC_MISMATCHED_ACOUSTICS
47
SM_RC_BAD_ACOUSTICS
48
SM_RC_SPELLING_TOO_LONG
49
SM_RC_ACOUSTICS_TOO_LONG
50 SM_RC_ADDWORD_LIMIT_EXCEEDED
60 SM_RC_SERVER_ERROR
61 SM_RC_SERVER_MALLOC_ERROR
62 SM_RC_SERVER_FILE_OPEN_ERROR
63 SM_RC_SERVER_FILE_WRITE_ERROR
64 SM_RC_SERVER_FILE_READ_ERROR
65 SM_RC_SERVER_FILE_CLOSE_ERROR
66 SM_RC_SERVER_PROCESS_ERROR
67 SM_RC_SERVER_TERMINATED
70 SM_RC_BAD_TAG
71 SM_RC_BAD_UTTNO
72 SM_RC_BAD_MESSAGE
80 SM_RC_NOT_DELETED
81 SM_RC_NOT_INVOCAB
82 SM_RC_INVOCAB
83 SM_RC_BAD_VOCAB
84 SM_RC_MISSING_EXTERN
90 SM_RC_BAD_USERID
91 SM_RC_BAD_ENROLLID
92 SM_RC_BAD_PASSWORD
93 SM_RC_BAD_TASKID
94 SM_RC_BAD_CLIENT
95 SM_RC_USERID_EXISTS
96
SM_RC_ENROLLID_EXISTS
97
SM_RC_USERID_BUSY
98
SM_RC_ENROLLID_BUSY
99
SM_RC_BAD_SCRIPT
100
SM_RC_BAD_DESCRIPTION
101
SM_RC_ENROLLID_RUNNING
102
SM_RC_ENROLLMENT_NOT_COMPLETE
IBM SMAPI Reference
103
SM_RC_MISMATCHED_LANGUAGE
104
SM_RC_MISMATCHED_ALPHABET
105
SM_RC_MISMATCHED_SCRIPT
106
SM_RC_BAD_LANGUAGE
107
SM_RC_BAD_NAME
108
SM_RC_INVALID_WINDOW_HANDLE
110 SM_RC_BAD_ITEM
111 SM_RC_BAD_VALUE
120 SM_RC_BUSY_LAST_UTTERANCE
121 SM_RC_B USY_WORD_CORRECTION
130 SM_RC_NO_SPACE
131 SM_RC_NO_SPACE_INIT_RECO
132 SM_RC_NO_SPACE_INIT_ENROLL
133 SM_RC_NO_SPACE_TERM_ENROLL
134 SM_RC_NO_SPACE_MIC_ON
140 SM_RC_INVALID_PARM_MAX_LEN
170 SM_RC_NO_FOCUS_APP
171 SM_RC_FOCUS_GRANTED
172 SM_RC_FOCUS_REQUEST_PENDING
173 SM_RC_FOCUS_DENIED
174 SM_RC_NAV_ALREADY_DEFINED
175 SM_RC_NOT_IN_NOTIFY
176 SM_RC_EXISTS_IN_NOTIFY
178 SM_RC_INCOMPATIBLE_ENROLLMENT
250 SM_RC_MAX_NAMES
1000 SM_RC_NOT_YET
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
Engine Return Codes and Messages
200
SM_RC_SM_NOT_OPEN
201
SM_RC_WRONG_SM_VERSION
202
SM_RC_SM_NOT_ACTIVE_CLIENT
203 SM_RC_SM_EINVAL_MSG_TYPE
204 SM_RC_REPLY_NULL
205 SM_RC_NO_MORE_CONNECTIONS
206 SM_RC_NO_TOPLEVEL_WIDGET
207 SM_RC_CONNECTION_CHANGED
208 SM_RC_CALLBACK_LIST_CHANGED
209 SM_RC_ASCII_ALREADY_SET
210 SM_RC_NOTHING_TO_DISPATCH
211 SM_RC_MAX_MSG_QUEUES_EXCEEDED
214 SM_RC_OPEN_SYNCH_QUEUE_FAILED
215 SM_RC_ALREADY_CONNECTED
216 SM_RC_ALREADY_OPENED
IBM SMAPI Reference
Status Codes and Messages
100
SM_STAT_PLAY_START
101
SM_STAT_PLAY_STOP
102
SM_STAT_BAD_AUDIO
103 SM_STAT_BAD_TAG
104 SM_STAT_BAD_UTTERANCE
105 SM_STAT_BAD_MESSAGE
106 SM_STAT_ENROLLMENT_RECORDING
107 SM_STAT_ENROLLMENT_RUNNING
108 SM_STAT_ENROLLMENT_FAILED
109 SM_STAT_ENROLLMENT_COMPLETE
110 SM_STAT_ENROLLMENT_BUSY
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SMAPI Message Types
These message values are defined in the SMCOMM.H file.
/* Recognizer to application */
SM_SET_REPLY 53
SM_QUERY_REPLY 54
SM_QUERY_LANGUAGES_REPLY 55
SM_QUERY_USERS_REPLY 56
SM_QUERY_ENROLLIDS_REPLY 57
SM_QUERY_TASKS_REPLY 58
SM_INIT_RECOGNIZER_REPLY 59
SM_SPARE_PUBLIC_1_REPLY 60
SM_MIC_ON_REPLY 61
SM_MIC_OFF_REPLY 62
SM_REQUEST_MIC_ON_REPLY 63
SM_REQUEST_MIC_OFF_REPLY 64
SM_RECOGNIZE_NEXT_WORD_REPLY 65
SM_PLAY_WORDS_REPLY 66
SM_PLAY_UTTERANCE_REPLY 67
SM_PLAY_MESSAGE_REPLY 68
SM_CANCEL_PLAYBACK_REPLY 69
SM_NEW_CONTEXT_REPLY 70
SM_EVENT_NOTIFY_REPLY 71
SM_QUERY_ALTERNATES_REPLY 72
SM_WORD_CORRECTION_REPLY 73
SM_CORRECT_TEXT_REPLY 74
SM_CORRECT_TEXT_CANCEL_REPLY 75
SM_QUERY_WORD_REPLY 76
SM_ADD_PRONUNCIATION_REPLY 77
SM_REMOVE_PRONUNCIATION_REPLY 78
SM_QUERY_PRONUNCIATIONS_REPLY 79
IBM SMAPI Reference
SM_DEFINE_VOCAB_REPLY 80
SM_ADD_TO_VOCAB_REPLY 81
SM_REMOVE_FROM_VOCAB_REPLY 82
SM_QUERY_ADDED_WORDS_REPLY 83
SM_ENABLE_VOCAB_REPLY 84
SM_DISABLE_VOCAB_REPLY 85
SM_UNDEFINE_VOCAB_REPLY 86
SM_QUERY_VOCABS_REPLY 87
SM_QUERY_ENABLED_VOCABS_REPLY 88
SM_SET_USER_INFO_REPLY 89
SM_QUERY_USER_INFO_REPLY 90
SM_DISCARD_DATA_REPLY 91
SM_HALT_RECOGNIZER_REPLY 92
SM_TERMINATE_RECOGNIZER_REPLY 93
SM_INIT_ENROLLMENT_REPLY 94
SM_TERMINATE_ENROLLMENT_REPLY 95
SM_INIT_DATABASE_REPLY 96
SM_TERMINATE_DATABASE_REPLY 97
SM_QUERY_PRONUNCIATION_REPLY 98
SM_REQUEST_FOCUS_REPLY 99
SM_RELEASE_FOCUS_REPLY 100
SM_QUERY_SESSIONS_REPLY 101
SM_DETACH_SESSIONS_REPLY 102
SM_SET_DEFAULT_REPLY 103
SM_QUERY_DEFAULT_REPLY 104
/* Unsolicited from recognizer to application */
SM_RECOGNIZED_TEXT 105
SM_RECOGNIZED_WORD 106
SM_UTTERANCE_COMPLETED 107
SM_PLAY_WORDS_STATUS 108
SM_PLAY_UTTERANCE_STATUS 109
SM_PLAY_MESSAGE_STATUS 110
SM_SERVER_STATUS 111
SM_EVENT_SYNCH 112
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_REPORT_ENGINE_ERROR 113
SM_FOCUS_LOST 114
SM_FOCUS_GRANTED 115
SM_REQUEST_DETACH 116
/* Unsolicited multicast group messages */
SM_AUDIO_LEVEL 117
SM_COMMAND_WORD 118
SM_MIC_STATE 119
SM_FOCUS_STATE 120
SM_ENGINE_STATE 121
/* Messages sent from application to engine and from engine to application*/
SM_REQUEST_MIC_ON 122
SM_REQUEST_MIC_OFF 123
/* Messages mapped from init mode to connect */
SM_CONNECT_REPLY 124
SM_DISCONNECT_REPLY 125
/* Sent from client to engine (for queues) to detach client */
SM_CLIENT_DETACH 126
/* Messages made public after 3.1 */
SM_DEFINE_GRAMMAR 143
SM_DEFINE_GRAMMAR_REPLY 150
IBM SMAPI Reference
/* Messages added after 3.1 for converged engine... added here to keep */
/* backward API compatibility */
SM_QUERY_SPEECH_DATA 169
SM_QUERY_SPEECH_DATA_REPLY 170
SM_SAVE_SPEECH_DATA 171
SM_SAVE_SPEECH_DATA_REPLY 172
SM_RESTORE_SPEECH_DATA 173
SM_RESTORE_SPEECH_DATA_REPLY 174
SM_RECOGNIZED_PHRASE 175
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SMAPI Message Explanations
The following are explanations for the SMAPI messages.
SM_RC_ACOUSTICS_TOO_LONG
The acoustics specified are too long.
Explanation:
The recording made for a specified word is longer than the phonetic representation of the
requested word.
User response:
Enter a phonetic spelling or record the word again.
SM_RC_ADDED
The specified word has been added to the speech vocabulary.
Explanation:
The request to add a word was successfully completed.
User response:
None
IBM SMAPI Reference
SM_RC_ADDWORD_LIMIT_EXCEEDED
The added-word limit has been reached.
Explanation:
Only a specified number of words can be added to a speaker's vocabulary. The speech system has
reached your added-word limit.
User response:
Review your added words and delete the ones that are either unneeded or infrequently used.
SM_RC_ALREADY_CONNECTED
Already connected to speech recognition engine.
Explanation:
Either SmConnect() or SmOpen() was called after the application had already successfully
connected to the engine.
User response:
Correct the application programming error.
SM_RC_ALREADY_OPENED
Already opened for connection to speech recognition engine.
Explanation:
A second call to SmOpen() was made after the application had already successfully opened the
local API data structure.
User response:
Correct the application programming error.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_ASSOC_EVENT_SEM_FAILED
An IPC error: Unable to associate semaphore.
Explanation:
Unable to associate semaphore.
User response:
Submit a problem report.
SM_RC_AUDIO_FORCED_MIC_OFF
The speech system has forced the microphone off.
Explanation:
The speech system turned off the microphone unexpectedly. This event can occur if the speech
system has an internal error or if the disk is full.
User response:
Try the request again. Save the log files of the session and submit a problem report.
SM_RC_AUDIO_IN_USE
The speech system is already in use.
Explanation:
The speech system is being used by another session.
User response:
Correct the application programming error.
IBM SMAPI Reference
SM_RC_AUDIO_OVERRUN
The speech system has overrun its recording buffers.
Explanation:
The speech system was not able to continue sending audio data because the recording buffers are
full.
User response:
Up to 100 seconds of audio can be stored in an internal audio memory buffer. For details, see
"Processing Speech Engine Audio" in the SMAPI Developer's Guide.
SM_RC_BAD_ACOUSTICS
Invalid acoustic data has been found.
Explanation:
The recorded data was not found for the word requested to be added.
User response:
Ensure that the disk is not full, which would cause files to be lost.
SM_RC_BAD_ADDWORD
The add-word process could not be initiated.
Explanation:
The speech recognition engine detected an error with the add word component.
User response:
Save the log files of the session and submit a problem report.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_BAD_AP
The system detected an error with the acoustic processor.
Explanation:
The speech recognition engine detected an error with the acoustic-processor component.
User response:
Save the log files of the session and submit a problem report.
SM_RC_BAD_AUDIO
The system detected an error with the audio source.
Explanation:
An application will get this return if there is a problem with the audio source (for example, if there
is a problem loading code on the adapter card during initialization).
User response:
Try the request again. If the problem persists, save the log files of the session, report the error, and
restart.
SM_RC_BAD_DECO
The system detected an error with the speech recognition engine.
Explanation:
The speech recognition engine detected an error with the decoding-processor component.
User response:
Save the log files of the session and submit a problem report.
IBM SMAPI Reference
SM_RC_BAD_DESCRIPTION
An invalid description has been specified.
Explanation:
An attempt was made to write an enrollment description containing a non-ASCII character or an
enrollment description that exceeded the maximum length.
User response:
Enter a description that is equal to or less than the maximum length and use only valid, printable
ASCII characters.
SM_RC_BAD_ENROLLID
An invalid enrollment identifier has been specified.
Explanation:
The enrollment ID for the specified speaker is not valid.
User response:
Select a valid enrollment ID for the specified user ID.
SM_RC_BAD_ITEM
An invalid item name has been specified.
Explanation:
An attempt was made to write an item name containing a non-ASCII character.
User response:
Enter an item name using only valid, printable ASCII characters.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_BAD_LANGUAGE
An invalid language has been specified, or this language is not installed.
Explanation:
The requested language is not valid or is not installed.
User response:
Specify a valid language for the installed speech recognition engine.
SM_RC_BAD_MESSAGE
An invalid audio message name has been specified.
Explanation:
An invalid audio message name was passed by the application to the SMAPI. This is an application
programming error.
User response:
Correct the application programming error.
SM_RC_BAD_MODE
The request is not valid in this speech recognition engine mode.
Explanation:
The speech recognition engine was initialized for a mode that does not support the requested
function. This is an application programming error.
User response:
Correct the application programming error.
IBM SMAPI Reference
SM_RC_BAD_NAME
An invalid name tag has been specified.
Explanation:
An attempt was made used to use an invalid name.
User response:
Specify a valid name.
SM_RC_BAD_SCRIPT
A bad script has been specified, or no scripts are available.
Explanation:
An attempt was made to use an invalid script for enrollment.
User response:
Specify a valid script.
SM_RC_BAD_TAG
An invalid word tag value has been specified.
Explanation:
An invalid tag value was passed by the application to the SMAPI. This is an application
programming error.
User response:
Correct the application programming error.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_BAD_TASKID
A match could not be found for the specified domain ID.
Explanation:
The domain ID is not valid.
User response:
Select a valid domain ID.
SM_RC_BAD_USERID
A match could not be found for the specified user ID.
Explanation:
The user ID is not valid.
User response:
Select a valid user ID.
SM_RC_BAD_UTTNO
An invalid utterance number has been specified.
Explanation:
An invalid utterance number was passed by the application to the SMAPI. This is an application
programming error.
User response:
Correct the application programming error.
IBM SMAPI Reference
SM_RC_BAD_VALUE
An invalid value has been specified.
Explanation:
An attempt was made to write a value containing a non-ASCII character.
User response:
Enter a value using only valid, printable ASCII characters.
SM_RC_BAD_VOCAB
The specified vocabulary is not valid.
Explanation:
An invalid vocabulary name was passed by the application to the SMAPI. This is an application
programming error.
User response:
Correct the application programming error.
SM_RC_BUSY_LAST_UTTERANCE
The speech recognition engine is busy processing the last utterance.
Explanation:
An attempt was made to play a message or word before all the speech had been processed after an
SmMicOff call.
User response:
Wait a few seconds and repeat the request until you receive a response.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_BUSY_WORD_CORRECTION
The speech recognition engine is busy processing the last word correction.
Explanation:
An attempt was made to correct a word and turn on the microphone before the previous request
was completed.
User response:
Wait a few seconds and repeat the request until you receive a response.
SM_RC_CALLBACK_LIST_CHANGED
The callback list has been changed during the execution of another callback.
Explanation:
The callback list has been modified while executing a callback procedure.
User response:
Correct the application programming error.
SM_RC_CONNECTION_CHANGED
New or closed connection when executing callback procedure.
Explanation:
A new connection to the SMAPI was created or an old one was removed from within a callback
procedure.
User response:
Submit a problem report.
IBM SMAPI Reference
SM_RC_CREATE_EVENT_SEM_FAILED
An IPC error: Unable to create event semaphore.
Explanation:
Unable to create event semaphore.
User response:
Submit a problem report.
SM_RC_CREATE_MBOX_FAILED
An IPC error: Unable to create mbox.
Explanation:
Unable to create mbox.
User response:
Submit a problem report.
SM_RC_DEEALLOCATING_SH_MEM
Unable to deallocate shared memory.
Explanation:
There is not sufficient memory for messages to pass between the SMAPI and the speech
recognition engine.
User response:
Try the request again. If the problem persists, record the error and submit a problem report.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_EALLBUSY
IBM ViaVoice is busy.
Explanation:
IBM ViaVoice is busy.
User response:
Try the request again. If the problem persists, record the error and submit a problem report.
SM_RC_EALLOC
Unable to allocate memory for speech recognition engine messages.
Explanation:
There is not sufficient memory for messages to pass between the SMAPI and the speech
recognition engine.
User response:
Record the error and submit a problem report.
SM_RC_EAPIVERSION
Incorrect API version.
Explanation:
The speech recognition engine and the SMAPI are not compatible.
User response:
Install a complete and compatible version.
IBM SMAPI Reference
SM_RC_EBADAPPNAME
An invalid application name has been specified.
Explanation:
An invalid application name was specified for a session between the SMAPI and the speech
recognition engine.
User response:
Correct the application programming error.
SM_RC_EBADHANDLE
Invalid handle passed to the speech recognition engine.
Explanation:
An invalid internal handle was used by the SMAPI.
User response:
Correct the application programming error.
SM_RC_EINVAL
Invalid value passed to speech recognition engine.
Explanation:
The value passed from the application to the SMAPI could not be passed to the speech recognition
engine.
User response:
Correct the application programming error.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_ENOCONN
No connection to speech recognition engine.
Explanation:
The application is unable to establish a session with the speech recognition engine; most likely,
this is because the speech recognition engine is not running.
User response:
Restart the speech recognition engine. If the system is running, verify that the level of the client
software and the level of the speech recognition engine are compatible.
SM_RC_ENOHANDLES
No handles for speech recognition engine.
Explanation:
An internal resource needed by the SMAPI is not available.
User response:
Restart the speech recognition engine.
SM_RC_ENOMEM
No memory available for speech recognition engine.
Explanation:
No memory is available for the speech recognition engine communications process.
User response:
Restart the speech recognition engine.
IBM SMAPI Reference
SM_RC_ENOMSG
No message available from speech recognition engine.
Explanation:
A request was made to the speech recognition engine but no response was received. A
communications error or a speech recognition engine error prevented the speech recognition
engine from responding to the application request.
User response:
Report the error and try the request again.
SM_RC_ENOSERVER
Unable to find an available speech recognition engine.
Explanation:
All speech recognition engines are being used by other users.
User response:
Wait a few minutes and try again to establish a session.
SM_RC_ENROLLID_BUSY
Enrollment is busy.
Explanation:
The enrollment ID is still being processed.
User response:
An attempt was made to use an enrollment ID that was locked. Try to use the enrollment ID later.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_ENROLLID_EXISTS
The specified enrollment identifier already exists.
Explanation:
An attempt was made to specify an enrollment ID that already exists for the specified user ID.
User response:
Provide a unique enrollment ID to the enrollment program.
SM_RC_ENROLLID_RUNNING
The enrollment data set specified is being processed.
Explanation:
A fully recorded enrollment data set is being processed and will be available for dictation when it
as been processed.
User response:
None.
SM_RC_ENROLLMENT_NOT_COMPLETE
Enrollment has not completed for this identifier.
Explanation:
An enrollment data set that is still being processed offline was specified for decoding.
User response:
Try to use the enrollment data set for dictating after the offline processing is completed.
IBM SMAPI Reference
SM_RC_FREE_MEM_ERROR
An IPC error: Error freeing memory.
Explanation:
Error freeing memory.
User response:
Submit a problem report.
SM_RC_EXISTS_IN_NOTIFY
Application is already in specified group
Explanation:
An application asks to enable a notification group in which the application is already registered.
User response:
None.
SM_RC_FOCUS_DENIED
A focus request has been denied.
Explanation:
The current application with speech focus has "grabbed" the focus and changes are being blocked
by the engine.
User response:
None.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_FOCUS_GRANTED
The application already has the speech focus.
Explanation:
The requesting application has already been granted speech focus and an asynchronous
notification message will not be sent by the engine.
User response:
None.
SM_RC_INCOMPATIBLE_ENROLLMENT
Enrollment was not compatible with the current engine.
Explanation:
An enrollment created for a previous release may not be supported on the current engine.
User response:
Re-enroll.
SM_RC_ILLEGAL_SPOKENLIKE
An invalid spoken-like spelling has been specified.
Explanation:
For a given language, certain ASCII characters are not valid.
User response:
Provide a valid spoken-like spelling for the language you are using.
IBM SMAPI Reference
SM_RC_ILLEGAL_SPELLING
An invalid spelling has been specified.
Explanation:
For a given language, certain ASCII characters are not valid.
User response:
Provide a valid spelling for the language you are using.
SM_RC_INVALID_PARM_MAX_LEN
The specified parameter exceeds the maximum length.
Explanation:
The specified parameter exceeds the maximum length permitted by the speech recognition engine.
User response:
Specify the parameter again.
SM_RC_INVOCAB
The specified word is in the speech recognition engine vocabulary.
Explanation:
The specified word already exists in the speech recognition engine vocabulary.
User response:
None.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_MIC_ALREADY_OFF
The microphone is already off.
Explanation:
A request was made to turn off the microphone, but it is already off.
User response:
None.
SM_RC_MIC_ALREADY_ON
The microphone is already on.
Explanation:
A request was made to turn on the microphone, but it is already on. This is an application
programming error.
User response:
Correct the application programming error.
SM_RC_MIC_OFF_PENDING
A microphone-off request is already in progress.
Explanation:
A request was made to turn off the microphone while it was in the process of being turned off. This
is an application programming error.
User response:
Correct the application programming error.
IBM SMAPI Reference
SM_RC_MIC_ON_PENDING
A microphone-on request is already in progress.
Explanation:
A request was made to turn on the microphone while it was in the process of being turned on. This
is an application programming error.
User response:
Correct the application programming error.
SM_RC_MISMATCHED_ACOUSTICS
An acoustics mismatch has been found.
Explanation:
The recording does not match the spelling provided for the added word.
User response:
Try recording the word again, or specify a spelling that phonetically matches the requested word.
SM_RC_MISMATCHED_ALPHABET
The domain and enrollment identifier specified are in different alphabets.
Explanation:
The domain specified is not for the same alphabet as the enrollment ID.
User response:
Specify a valid domain for the alphabet in which you want to dictate.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_MISMATCHED_LANGUAGE
The domain and enrollment identifier specified are in different languages.
Explanation:
The specified domain is not for the same language as the enrollment ID.
User response:
Specify a valid domain for the language in which you want to dictate.
SM_RC_MISMATCHED_SCRIPT
The script specified does not match the previously specified script.
Explanation:
A partially recorded enrollment used a script that is different from the one currently specified.
User response:
Use the script specified in the last session to continue the enrollment session.
SM_RC_MISSING_EXTERN
A required external vocabulary does not exist.
Explanation:
An external vocabulary referenced in a grammar has not been defined.
User response:
None.
IBM SMAPI Reference
SM_RC_MULTIPLE_SPELLINGS
Multiple spellings specified.
Explanation:
More than one spelling was specified for an added-word or more than one tag was specified. This
is an application programming error.
User response:
Correct the application programming error.
SM_RC_NAV_ALREADY_DEFINED
Navigator application already defined.
Explanation:
A second application has attempted to assert the navigator field.
User response:
None.
SM_RC_NO_FOCUS_APP
No application has the speech focus.
Explanation:
A request has been made to turn the microphone on, but no application has speech focus.
User response:
Request speech focus for an application.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_NO_MORE_CONNECTIONS
Duplicate SmOpen call.
Explanation:
The SmOpen function was called again without previously closing the connection to the SMAPI
through SmClose.
User response:
This is an application programming error.
SM_RC_NO_SPACE
No space is left on the disk.
Explanation:
No space is left on the disk.
User response:
None.
SM_RC_NO_SPACE_INIT_ENROLL
No space is left on the disk for an enrollment session.
Explanation:
Not enough disk space is available to record the next sentence during enrollment.
User response:
Restart the speech recognition engine.
IBM SMAPI Reference
SM_RC_NO_SPACE_INIT_RECO
No space is left on the disk for a recognition session.
Explanation:
Not enough disk space is available to record the next sentence during dictation.
User response:
None.
SM_RC_NO_SPACE_MIC_ON
No space is left on the disk for PCM.
Explanation:
No space is left on the disk for PCM.
User response:
None.
SM_RC_NO_SPACE_TERM_ENROLL
Not enough disk space to complete training.
Explanation:
Not enough disk space available to complete training.
User response:
Restart the speech recognition engine.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_NOT_ADDED
The specified word has not been added to the speech recognition engine vocabulary.
Explanation:
The add-word request was not successfully completed. For a given language, a request to add a
word might fail.
User response:
Try a new recording of the word or provide a phonetic spelling.
SM_RC_NOT_DELETED
The speech recognition engine was unable to delete the specified added word.
Explanation:
The speech recognition engine attempted to delete a word that is not in the specified vocabulary.
User response:
Correct the application programming error.
SM_RC_NOT_IN_NOTIFY
Application is not in the specified group.
Explanation:
An application asks to disable a notification group in which the application is not registered.
User response:
None.
IBM SMAPI Reference
SM_RC_NOT_INVOCAB
The specified word is not in the speech recognition engine vocabulary.
Explanation:
The specified word does not exist in the speech recognition engine vocabulary.
User response:
None.
SM_RC_NOT_VALID_REQUEST
The engine is not in the proper state to handle this request.
Explanation:
The engine is not in the proper state to handle this request.
User response:
Correct the application programming error.
SM_RC_NOT_WHILE_MIC_ON
The given request is not valid while the microphone is on.
Explanation:
Some requests are not valid when the microphone is on. This is an application programming error.
User response:
Turn off the microphone before making the request.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_NOT_WHILE_PLAYING
The given request is not valid while playing audio.
Explanation:
Some requests are not valid while audio is playing. This is an application programming error.
User response:
Wait until the audio has finished playing before making this request.
SM_RC_NOT_YET
SMAPI function call not supported.
Explanation:
The application made a function call that is not supported by the installed SMAPI. The supporting
function in the speech recognition engine is not present. All applications must match the installed
SMAPI.
User response:
If a new application is installed, ensure that it matches the installed SMAPI or install the required
SMAPI and upgrade the existing applications.
SM_RC_OK
Successful completion.
Explanation:
The most recent application request to the SMAPI was successfully completed.
User response:
None.
IBM SMAPI Reference
SM_RC_OPEN_SYNCH_QUEUE_FAILED
SmOpen failed to get required resources.
Explanation:
A system problem occurred during the SmOpen call when certain system resources are allocated.
User response:
Try the request again. If the problem persists, report the error and restart the speech system. Save
the log files of the session and submit a problem report on the speech recognition engine.
SM_RC_PLAY_OPEN_ERROR
The system was unable to open the play device.
Explanation:
The speech recognition engine was not able to open the play device. Another application is using
the IBM VoiceType Dictation Adapter or the device driver was replaced by another application.
User response:
Try the request again. If the problem persists, report the error and restart the speech system. Save
the log files of the session and submit a problem report on the speech recognition engine.
SM_RC_QUEUE_CLOSE_ERROR
An IPC error: Error closing queue.
Explanation:
Error closing queue.
User response:
Try the request again. If the problem persists, submit a problem report.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_RECORD_OPEN_ERROR
The system was unable to open the recording device.
Explanation:
The speech recognition engine was not able to open the recording device. Another application is
using the IBM VoiceType Dictation Adapter or the device driver was replaced by another
application.
User response:
Try the request again. If the problem persists, report the error and restart the speech system. Save
the log files of the session and submit a problem report on the speech recognition engine.
SM_RC_REPLY_NULL
NULL reply parameter.
Explanation:
The pointer to the reply structure that was given to one of the reply message functions is NULL.
User response:
Correct the application programming error.
SM_RC_SERVER_ERROR
The speech recognition engine detected an internal error.
Explanation:
The speech recognition engine has detected an internal error.
User response:
Save the log files of the session. Ensure that sufficient disk space is available for the system.
Restart the speech recognition engine.
IBM SMAPI Reference
SM_RC_SERVER_FILE_CLOSE_ERROR
The speech recognition engine has an internal close error.
Explanation:
The speech recognition engine was not able to close one of its files.
It is possible that, because of the additional applications running on the speech recognition engine,
the maximum number of open file handles, the microprocessor limits, or the page space limits have
been reached.
User response:
Save the log files of the session. Ensure that sufficient disk space is available for the system.
Restart the speech recognition engine.
SM_RC_SERVER_FILE_OPEN_ERROR
The speech recognition engine has an internal open error.
Explanation:
The speech recognition engine was not able to open one of its files.
It is possible that, because of the additional applications running on the speech recognition engine,
the maximum number of open file handles, the microprocessor limits, or the page space limits have
been reached.
User response:
Save the log files of the session. Ensure that sufficient disk space is available for the system.
Restart the speech recognition engine.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_SERVER_FILE_READ_ERROR
The speech recognition engine has an internal read error.
Explanation:
The speech recognition engine was not able to read one of its files.
It is possible that, because of the additional applications running on the speech recognition engine,
the maximum number of open file handles, the microprocessor limits, or the page space limits have
been reached.
User response:
Save the log files of the session. Ensure that sufficient disk space is available for the system.
Restart the speech recognition engine.
SM_RC_SERVER_FILE_WRITE_ERROR
The speech recognition engine has an internal write error.
Explanation:
The speech recognition engine was not able to write one of its files.
It is possible that, because of the additional applications running on the speech recognition engine,
the maximum number of open file handles, the microprocessor limits, or the page space limits have
been reached.
User response:
Save the log files of the session. Ensure that sufficient disk space is available for the system.
Restart the speech recognition engine.
IBM SMAPI Reference
SM_RC_SERVER_MALLOC_ERROR
The speech recognition engine has an internal malloc error.
Explanation:
The speech recognition engine was not able to allocate memory for its process.
User response:
Save the log files of the session. Ensure that sufficient memory is available for the system. Restart
the speech recognition engine.
SM_RC_SERVER_PROCESS_ERROR
The speech recognition engine has an internal process error.
Explanation:
The speech recognition engine had an unrecoverable error.
It is possible that, because of the additional applications running on the speech recognition engine,
the maximum number of open file handles, the microprocessor limits, or the page space limits have
been reached.
User response:
Save the log files of the session. Ensure that sufficient disk space is available for the system.
Restart the speech recognition engine.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_SERVER_TERMINATED
speech recognition engine terminated.
Explanation:
The speech recognition engine has stopped.
User response:
Save the log files of the session and restart the speech recognition engine.
SM_RC_SM_EINVAL_MSG_TYPE
Invalid message type.
Explanation:
This is a program logic error. The program has used an access function against an invalid message
type.
User response:
Use an access function that is valid for the message type.
SM_RC_SM_NOT_ACTIVE_CLIENT
The speech-aware application is not active.
Explanation:
The speech-aware application is not active.
User response:
Correct the application programming error.
IBM SMAPI Reference
SM_RC_SM_NOT_OPEN
Application has not opened SMAPI using an SmOpen call.
Explanation:
The speech application has not been opened by an SmOpen call.
User response:
Correct the application programming error.
SM_RC_SUB_UNSET_ERROR
An IPC error: Error unsetting memory.
Explanation:
The speech application has not been opened by an SmOpen call.
User response:
Correct the application programming error.
SM_RC_SPELLING_TOO_LONG
The spelling specified is too long.
Explanation:
The specified word is too long.
User response:
The spelling of the specified word is phonetically longer than the recording made for the word.
Enter a phonetic spelling or record the word again.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_RC_USERID_BUSY
User identifier is busy.
Explanation:
An attempt was made to use a user ID that was locked by another client workstation or application.
User response:
Try to use the user ID later.
SM_RC_USERID_EXISTS
User identifier already exists.
Explanation:
An attempt was made to add a user ID that already exists on the speech recognition engine.
User response:
Provide a unique user ID to the program.
SM_RC_WRONG_SM_VERSION
Incompatible versions of compiled/dynamically linked SMAPI.
Explanation:
The version of the SMAPI with which the application has been compiled is different from that of
the installed run-time libraries.
User response:
Compile your application with the same version of the API currently installed on your computer.
IBM SMAPI Reference
SM_STAT_BAD_AUDIO
Bad audio.
Explanation:
The connection to the audio source was lost during playback.
User response:
Try the request again.
SM_STAT_BAD_MESSAGE
Bad message.
Explanation:
An invalid message was specified for playback. This is an application programming error.
User response:
Try again with a valid message.
SM_STAT_BAD_TAG
Bad tag.
Explanation:
An invalid word tag was specified for playback. This is an application programming error.
User response:
Try again with a valid word tag.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_STAT_BAD_UTTERANCE
Bad utterance.
Explanation:
An invalid utterance was specified for playback. This is an application programming error.
User response:
Try again with a valid utterance.
SM_STAT_ENROLLMENT_BUSY
Enroll ID is busy.
Explanation:
This enroll ID is locked through use from a different machine.
User response:
Try to use the enroll ID later.
SM_STAT_ENROLLMENT_COMPLETE
Enrollment complete.
Explanation:
Training completed successfully for this enroll ID. This is informational only.
User response:
None.
IBM SMAPI Reference
SM_STAT_ENROLLMENT_FAILED
Enrollment failed.
Explanation:
The training process failed for this enroll ID.
User response:
Refer to the help for Enrollment.
SM_STAT_ENROLLMENT_RECORDING
Enrollment recording.
Explanation:
The user is recording the enrollment script for this enroll ID. This is informational only.
User response:
None.
SM_STAT_ENROLLMENT_RUNNING
Enrollment running.
Explanation:
The engine is running training for this enroll ID. This is informational only.
User response:
None.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
SM_STAT_PLAY_START
Audio play started.
Explanation:
The message, word, or utterance has started playing. This is informational only.
User response:
None.
SM_STAT_PLAY_STOP
Audio play stopped.
Explanation:
The message, word, or utterance has stopped playing. This is informational only.
User response:
None.
IBM SMAPI Reference
ROUTER.MSG Log
Logs used for debugging are disabled by default. Logging is controlled by the value setting of the
parameter api_log_level in the following file:
(IBMVType)/bin/engine.cfg
This file should be used for debugging and diagnostics. The content of the file is not defined as a public
interface.
The value settings for logging are:
0 Disables logging
1 Message headers
2 Message headers + content
3 Message headers + content + internal engine mes
sages
>3 Reserved
After this logging parameter has been changed the engine must be restarted before the new parameter
value can take effect.
Logs of interest are located in the following IBM ViaVoice host-drive directory:
(IBMVType/Temp)
The log file, router.msg, includes a trace of IBM ViaVoice SMAPI calls. Differences between SMAPI
names in this log file and the documentation include the following:
. "SPCH_" prefix in the log file and "Sm" prefix in the documentation.
. Underscore("_") is used in the log file, but not in the documentation.
IBM ViaVoice SDK for Windows
SMAPI Return Codes and Messages
An explanation of reply message structures that can be logged but will not be seen by the application
include the following:
SM_INIT_DATABASE_REPLY
Response to an asynchronous SmConnect that is establishing a database session but is presented to
the application as a SM_CONNECT_REPLY reply message structure.
SM_INIT_RECOGNIZER_REPLY
Response to an asynchronous SmConnect that is establishing a recognition session but is presented
to the application as a SM_CONNECT_REPLY reply message structure.
SM_TERMINATE_DATABASE_REPLY
Response to an asynchronous SmDisconnect that is disconnecting from the speech recognition
engine during a database session but is presented to the application as a
SM_DISCONNECT_REPLY reply message structure.
SM_TERMINATE_RECOGNIZER_REPLY
Response to an asynchronous SmDisconnect that is disconnecting from the speech recognition
engine during a recognition session but is presented to the application as a
SM_DISCONNECT_REPLY reply message structure.
IBM SMAPI Reference
IBM ViaVoice SDK for Windows
Appendix B DMAPI Return Codes
and Messages
These return codes and messages, defined in DMAPI.H, are generated by DMAPI.
DMAPI Return Codes and Messages
The following list contains the return code values in numeric order for DMAPI. Return codes marked
with an asterisk (*) are used internally by the Dictation Macro Editor and are not returned to the
application.
0 DM_ERR_OK
1 DM_ERR_TEMPLATE_NOT_FOUND
2 DM_ERR_MACRO_NOT_FOUND
3 DM_ERR_MALLOC
4 DM_ERR_INVALID_USERID
5 DM_ERR_INVALID_DOMAIN
6 DM_ERR_INVALID_LANGUAGE
7 DM_ERR_INVALID_HANDLE
8 DM_ERR_INVALID_MACRO
9 DM_ERR_INVALID_TEMPLATE *
10 DM_ERR_DUPLICATE_MACRO
11 DM_ERR_FILE_READ *
12 DM_ERR_NOTIFY_EXCEEDED
13 DM_ERR_OPEN_CLIPBOARD_FAILED *
14 DM_ERR_NOT_ENOUGH_SHARED_MEM *
15 DM_ERR_SHARED_MEM_UNDEFINED *
16 DM_ERR_TRANSFER_TO_CLIPBRD *
17 DM_ERR_MISSING_CLIPBRD_FORMAT *
18 DM_ERR_INVALID_MACROFILE
19 DM_ERR_INVALID_MACROVERSION *
20 DM_ERR_INVALID_MACRORELEASE *
IBM SMAPI Reference
21 DM_ERR_MACRO_NESTING *
22 DM_ERR_INVALID_KEYWORD
23 DM_ERR_INVALID_KEYTYPE
24 DM_ERR_INVALID_KEYWORD
25 DM_ERR_EMFILE
26 DM_ERR_ENOENT
29 DM_ERR_UNDEFINED
30 DM_ERR_LOAD_RESOURCE_DLL
31 DM_ERR_EBADF
32 DM_ERR_ENOSPC *
33 DM_ERR_ACT_FILE_PARSE *
34 DM_ERR_INI_FILE_PARSE *
35 DM_ERR_EXPDLL_TIMEOUT
36 DM_ERR_EXPDLL_QUERYFUN_FAILED
37 DM_ERR_EXPDLL_LOAD_FAILED
38 DM_ERR_EXPDLL_ERR
39 DM_ERR_SYSTEM_PARM_LONG
40 DM_ERR_OUT_OF_SYSTEM_RES
41 DM_ERR_BAD_EXE_FORMAT
42 DM_ERR_NOUPDATE
43 DM_ERR_SET_AFFECT_FLAG *
44 DM_ERR_UNEXPECTED_EOF *
IBM ViaVoice SDK for Windows
DMAPI Return Codes and Messages
DMAPI Message Explanations
The following are explanations for the DMAPI messages.
DM_ERR_ACT_FILE_PARSE
Explanation:
This error code is used internally by the Dictation Macro Editor.
User response:
None.
DM_ERR_BAD_EXE_FORMAT
Explanation:
The specified EXE file is invalid. It may be a non-Win32 EXE, or there may be an error in the EXE
image.
User response:
Correct the application programming error.
DM_ERR_DUPLICATE_MACRO
Explanation:
An attempt was made to load an already existing macro.
User response:
None.
IBM SMAPI Reference
DM_ERR_EACCESS
Explanation:
An error occurred attempting to access a macro file. Either the specified file is a directory, or you
attempted to write to a read-only file.
User response:
Correct the file name and try the call again.
DM_ERR_EBADF
Explanation:
The file is not opened.
User response:
Correct the application programming error.
DM_ERR_EMFILE
Explanation:
No more file handles are available.
User response:
Correct the application programming error.
IBM ViaVoice SDK for Windows
DMAPI Return Codes and Messages
DM_ERR_ENOENT
Explanation:
The specified file or path was not found.
User response:
Try again with a different file or path name.
DM_ERR_ENOSPC
Explanation:
This error code is used internally by the Dictation Macro Editor.
User response:
None.
DM_ERR_EXPDLL_ERR
Explanation:
An error occurred executing a DLL function.
User response:
Correct the application programming error.
IBM SMAPI Reference
DM_ERR_EXPDLL_LOAD_FAILED
Explanation:
DMAPI was unable to load a DLL.
User response:
Correct the application programming error.
DM_ERR_EXPDLL_QUERYFUN_FAILED
Explanation:
DMAPI was unable to load a function of a DLL.
User response:
Correct the application programming error.
DM_ERR_EXPDLL_TIMEOUT
Explanation:
The execution of a DLL function timed out.
User response:
Make sure that the call does not take longer than two seconds.
IBM ViaVoice SDK for Windows
DMAPI Return Codes and Messages
DM_ERR_FILE_READ
Explanation:
This error code is used internally by the Dictation Macro Editor.
User response:
None.
DM_ERR_INI_FILE_PARSE
Explanation:
This error code is used internally by the Dictation Macro Editor.
User response:
None.
DM_ERR_INVALID_DOMAIN
Explanation:
An invalid domain name was passed to DMAPI.
User response:
Correct the domain name and try the call again.
IBM SMAPI Reference
DM_ERR_INVALID_HANDLE
Explanation:
An invalid macro handle was passed to DMAPI.
User response:
Correct the macro handle and try the call again.
DM_ERR_INVALID_KEYTYPE
Explanation:
An invalid key type was passed to DMAPI.
User response:
Correct the type and try the call again.
DM_ERR_INVALID_KEYWORD
Explanation:
An invalid keyword was passed to DMAPI.
User response:
Correct the keyword and try the call again.
IBM ViaVoice SDK for Windows
DMAPI Return Codes and Messages
DM_ERR_INVALID_LANGUAGE
Explanation:
An invalid language code was passed to DMAPI.
User response:
Correct the language code and try the call again.
DM_ERR_INVALID_MACRO
Explanation:
An attempt was made to load an invalid macro. The macro file may be corrupted.
User response:
None.
DM_ERR_INVALID_MACROFILE
Explanation:
The macro file specified is invalid.
User response:
Correct the macro file name and try again.
IBM SMAPI Reference
DM_ERR_INVALID_MACRORELEASE
Explanation:
This error code is used internally by the Dictation Macro Editor.
User response:
None.
DM_ERR_INVALID_MACROVERSION
Explanation:
This error code is used internally by the Dictation Macro Editor.
User response:
None.
DM_ERR_INVALID_TEMPLATE
Explanation:
This error code is used internally by the Dictation Macro Editor.
User response:
None.
IBM ViaVoice SDK for Windows
DMAPI Return Codes and Messages
DM_ERR_INVALID_USERID
Explanation:
An invalid user ID was passed to DMAPI.
User response:
Correct the user ID and try the call again.
DM_ERR_LOAD_RESOURCE_DLL
Explanation:
DMAPI was unable to load the specified DLL.
User response:
Correct the application programming error.
DM_ERR_MACRO_NESTING
Explanation:
This error code is used internally by the Dictation Macro Editor.
User response:
None.
IBM SMAPI Reference
DM_ERR_MACRO_NOT_FOUND
Explanation:
DMAPI was unable to find the specified macro. Either a macro does not exist by that name, or you
specified an incorrect name.
User response:
Try the call again with a different macro name.
DM_ERR_MALLOC
Explanation:
A memory allocation failure occurred.
User response:
Correct the application programming error.
DM_ERR_MISSING_CLIPBRD_FORMAT
Explanation:
This error code is used internally by the Dictation Macro Editor.
User response:
None.
IBM ViaVoice SDK for Windows
DMAPI Return Codes and Messages
DM_ERR_NOT_ENOUGH_SHARED_MEMORY
Explanation:
This error code is used internally by the Dictation Macro Editor.
User response:
None.
DM_ERR_NOTIFY_EXCEEDED
Explanation:
The maximum number of Dictation Macro Editor sessions has been exceeded.
User response:
Close a Dictation Macro Editor session and try the call again.
DM_ERR_NOUPDATE
Explanation:
This error is returned by DmUpdate when no changes have been made to any macros or templates
since the last DmUpdate call.
User response:
None.
IBM SMAPI Reference
DM_ERR_OK
Explanation:
No error occurred.
User response:
None.
DM_ERR_OPEN_CLIPBOARD_FAILED
Explanation:
This error code is used internally by the Dictation Macro Editor.
User response:
None.
DM_ERR_OUT_OF_SYSTEM_RES
Explanation:
The system is out of memory or other system resources.
User response:
Correct the application programming error.
IBM ViaVoice SDK for Windows
DMAPI Return Codes and Messages
DM_ERR_FILE_SET_AFFECT_FLAG
Explanation:
This error code is used internally by the Dictation Macro Editor.
User response:
None.
DM_ERR_SHARED_MEM_UNDEFINED
Explanation:
This error code is used internally by the Dictation Macro Editor.
User response:
None.
DM_ERR_SYSTEM_PARM_LONG
Explanation:
A parameter specified in a system call is too long.
User response:
Correct the error and try the call again.
IBM SMAPI Reference
DM_ERR_TEMPLATE_NOT_FOUND
Explanation:
DMAPI was unable to find the specified template. Either a template does not exist by that name, or
you specified an incorrect name.
User response:
Try the call again with a different template name.
DM_ERR_TRANSFER_TO_CLIPBRD
Explanation:
This error code is used internally by the Dictation Macro Editor.
User response:
None.
DM_ERR_UNDEFINED
Explanation:
An undefined file access error occurred.
User response:
Correct the application programming error.
IBM ViaVoice SDK for Windows
DMAPI Return Codes and Messages
DM_ERR_UNEXPECTED_EOF
Explanation:
This error code is used internally by the Dictation Macro Editor.
User response:
None.
IBM SMAPI Reference
IBM ViaVoice SDK for Windows
Appendix C Speech Recognition
Engine Error Messages
These error messages are generated by the speech recognition engine. They can be found in the
error.log and engine.log files, which are located in the engine's working directory.
Bad Data in File '%s'
Indicates problems with data found in a successfully opened file. Files have been damaged or
incompatible speech data is being used. Restore the file indicated from backup or reinstall IBM
ViaVoice.
Bad Value '%s' for Tag '%s' in File '%s'
Control data is inconsistent. Files have been damaged or incompatible speech data is being used.
Restore the file indicated from backup or reinstall the IBM ViaVoice.
Duplicate Use of Vocabulary Name '%s'
A duplicate name has been used to define a vocabulary (static or dynamic). This is an application
programming error.
Exceeded Limit of %d %s
A system limit has been exceeded; for example, the maximum number of defined vocabularies is
100.
Failed to Open File '%s'
The specified file failed to open successfully. The file has probably been inadvertently erased.
Restore the file indicated from backup or reinstall IBM ViaVoice.
Missing Tag '%s' in File '%s'
A required control parameter (tag) was not found in the specified file. Control data is inconsistent.
Files have been damaged or incompatible speech data is being used. Restore the file indicated from
backup or reinstall IBM ViaVoice.
IBM SMAPI Reference
Severe Error in %s (%d)
A variety of severe error conditions that typically terminate the recognition session. File write
errors indicate file system problems (for example, the hard disk is full).
Mailbox
Errors might occur if one of the engine tasks fails and communication breaks down. Therefore, this
error is most likely secondary to the primary problem.
Label Buffer Overrun
In these cases the session is not ended, only the microphone is forced off. This situation is caused
by a very long pause in dictation (approximately 30 seconds) or by an ill-behaved application that
turns on the microphone and fails to ask for recognized words.
IBM ViaVoice SDK for Windows
Appendix D Notices
References in this publication to IBM products, programs, or services do not imply that IBM intends to
make these available in all countries in which IBM operates. Any reference to an IBM product,
program, or service is not intended to state or imply that only that IBM product, program, or service
may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any
functionally equivalent product, program, or service may be used instead of the IBM product, program,
or service. The evaluation and verification of operation in conjunction with other products, except
those expressly designated by IBM, are the responsibility of the user.
IBM may have patents or pending patent applications covering subject matter in this document. The
furnishing of this document does not give you any license to these patents. You can send license
inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
500 Columbus Avenue
Thornwood, NY 10594
U.S.A.
Asia-Pacific users can inquire, in writing, to the IBM Director of Intellectual Property and Licensing,
IBM World Trade Asia Corporation, 2-31 Roppongi 3-chome, Minato-ku, Tokyo 106, Japan.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the
exchange of information between independently created programs and other programs (including this
one) and (ii) the mutual use of the information which has been exchanged, should contact IBM
Corporation, Department LZKS, 11400 Burnet Road, Austin, TX 78758 U.S.A. Such information may
be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
IBM SMAPI Reference
Trademarks
The following terms are trademarks of the IBM Corporation in the United States or other countries or
both:
IBM
Lotus
Visual Age
ViaVoice
VoiceType
The following terms are trademarks of other companies:
Intel
Pentium
Intel Corporation
Microsoft, Windows, NT, the Windows 95 logo, Visual Basic, Visual C++, Visual J++ and Developer
Studio are trademarks or registered trademarks of Microsoft Corporation.
Other company, product, and service names, which may be denoted by an asterisk (**), may be
trademarks or service marks of others.
IBM ViaVoice SDK for Windows
Index
A
access functions, data 22
added pronunciations, querying 127, 129
added words, querying 107, 109
adding
new pronunciation 40
single callback routine 39
words to vocabulary 43
administrative functions 27
alphabets, retrieving 193
alternative words, requesting a list 112
alternative words, retrieving 195
annotations, retrieving 196
API
calls, parallel session 29
starter set
command and control 31
dictation 34
application
callbacks executed by 76
closing down and disconnecting engine 34
detaching from speech engine 67
disconnecting speech engine 34
establishing recognition session 35
processing recognized commands 33
receiving reply message structures 281
retrieving name of 198, 199
writing new 31
archive size, retrieving 245
archived file name, retrieving 243
ASCII string, returning 278
associating pronunciation with a spelling 40
attribute handling functions 22
attributes
SMAPI 305
audio
data, discarding 70, 72
file, playing prerecorded 91
functions 28
audio message name, retrieving 222
audio signal, retrieving level 200
available languages, querying 121, 123
B
beginning text dictation at a new document
location 87
C
caddr_t 299
callback
dispatching 76
functions 22
removing routine 153
callbacks
speech engine/router 292
cancelling
request for playback 49
changing text context sent to speech engine 87
checking
specified word in active vocabularies 147
version of SMAPI 46
closing
connection to speech engine 74
codepage, returning 202
command
processing recognized 33
starter set APIs 31
vocabulary. dynamically change 43
communication, closing with speech engine 74
compatibility, checking SMAPI and API 46
connecting to speech engine 52
connection
closing SMAPI 51
detaching all applications from speech
engine 67
functions 25
initializing values 89
control
starter set APIs 31
correcting errors 37
correcting misrecognized word 188
current speech data, saving 165
current vocabularies enabled, querying 117
IBM SMAPI Reference
D
data
access functions 22
discarding audio and error-correction 70, 72
querying speech 134
data access functions
SmGetAlphabets 193
SmGetAlternates 195
SmGetAnnotations 196
SmGetApplication 198
SmGetApplications 199
SmGetAudioLevel 200
SmGetCodePage 202
SmGetDescriptions 203
SmGetEngineState 205
SmGetEnrollId 207
SmGetEnrollIds 208
SmGetEventId 210
SmGetEventOptions 211
SmGetFirmWords 212
SmGetFlags 213
SmGetFocusChangeReason 215
SmGetFocusState 216
SmGetGrammarPath 217
SmGetIncrements 218
SmGetItemValue 219
SmGetLanguages 220
SmGetMicState 221
SmGetMsgName 222
SmGetMsgType 223
SmGetNameValue 224
SmGetNumberWordMsgs 225
SmGetOptions 226
SmGetPercentages 227
SmGetPhraseScore 228
SmGetPhraseState 229
SmGetPreferred 231
SmGetPronunciations 232
SmGetRc 233
SmGetRcDescription 234
SmGetRcName 235
SmGetSampleRates 236
SmGetScriptFlags 237
SmGetScripts 238
SmGetService 239
SmGetSessionId 240
SmGetSeverity 241
SmGetSizes 242
SmGetSpeechDataArchive 243
SmGetSpeechDataOptions 244
SmGetSpeechDataSize 245
SmGetSpeechDataVersion 246
SmGetSpelling 247
SmGetSpellings 249
SmGetStates 251
SmGetStatus 252
SmGetTags 254
SmGetTask 255
SmGetTaskFlags 256
SmGetTasks 257
SmGetTimes 258
SmGetTopics 260
SmGetTrained 261
SmGetUserId 262
SmGetUserIds 264
SmGetUsers 266
SmGetUtteranceNumber 267
SmGetVocabList 268
SmGetVocabName 269
SmGetVocabPath 271
SmGetVocWords 272
SmGetWords 274
SmGetWordTimes 275
SmGtBinaryItemValue 201
SmReturn 277
SmReturnRcDescription 278
SmReturnRcName 279
data type
VtArg 363
data types
caddr_t 299
DM_MACRO_STRUCT 350
DM_TEMPLATE_FIELD 352
DMERROR 349
SM_ANNOTATIONl 301
SM_VOCWORD 302
SM_WORD 303
SmArg 299
SmArgVal 300
SmHandler 300
IBM ViaVoice SDK for Windows
SmMsg 302
database functions 26
default
values
querying 115
setting 179
defined vocabulary
disabling 68
enabling 77
defining
grammar-based vocabulary 57
deleting dynamic vocabulary 186
detaching
one or more sessions 67
dictation
starter set APIs 34
direct calls to speech engine 39
disabling
defined vocabulary 68
discarding
audio data 70, 72
error-correction data 70, 72
disconnecting
engine 34
speech engine 38, 74
dispatching functions 22
DM_MACRO_STRUCT 350
DM_TEMPLATE_FIELD 352
DMAPI
message explanations 425
messages 423
return codes 423
DmClose 313
DMERROR 349
DmFlushEx 314
DmFreeMacro 315
DmFreeMacroEx 316
DmFreeNames 317
DmGetGroupsOnPage 318
DmGetKey 319
DmGetKeyGroup 320
DmGetKeyGroupOption 321
DmGetKeyGroupOptionSelection 322
DmGetLastError 323
DmGetMacro 325
DmGetMacroEx 327
DmGetNumberOfGroups 329
DmGetNumberOfOptions 330
DmGetNumberOfSelections 331
DmGetTemplate 332
DmIsNumberFlagged 334
DmKeywordFromType 335
DmOpen 337
DmQueryDelimiters 339
DmQueryMacroNames 340
DmQuerySetAndStoreKey 342
DmQueryTemplateNames 341
DmSetKey 343
DmStartMacroEditor 344
DmStoreKey 345
DmTypeFromKeyword 346
DmUpdate 348
domains, querying list 135, 137
dynamic actions
change, command vocabularies 43
creating
new vocabulary 60, 63
defining
new vocabulary 57
dynamic vocabulary, deleting 186
E
enabling
defined vocabulary 77
vocabularies 32, 35
enabling recognition of next word 150
engine
directing to process speech 33, 36
disconnecting 34
disconnecting from 38
establishing a recognition session 32
establishing recognition session 35
engine messages
SMAPI 373
engine return codes
SMAPI 373
enrollment
querying user IDs 119
enrollment IDs, retrieving 203
enrollment status, retrieving 251
error messages
speech engine 441
error-correction
data, discarding 70, 72
IBM SMAPI Reference
playing back spoken words 97
utterance playback 94
errors, correcting speech recognition 37
establishing connection to speech engine 52
event ID, retrieving 210
F
firm words, retrieving 212
flags, retrieving 213
focus state, retrieving 216
format
function call descriptions 19
FSG file, retrieving path 217
function
call descriptions, format 19
calls to speech engine 39
calls, SMAPI 22
data access 22
requesting list of alternative words 112
function calls
DmClose 313
DmFlushEx 314
DmFreeMacro 315
DmFreeMacroEx 316
DmFreeNames 317
DmGetGroupsOnPage 318
DmGetKey 319
DmGetKeyGroup 320
DmGetKeyGroupOption 321
DmGetKeyGroupOptionSelection 322
DmGetLastError 323
DmGetMacro 325
DmGetMacroEx 327
DmGetNumberOfGroups 329
DmGetNumberOfOptions 330
DmGetNumberOfSelections 331
DmGetTemplate 332
DmIsNumberFlagged 334
DmKeywordFromType 335
DmOpen 337
DmQueryDelimiters 339
DmQueryMacroNames 340
DmQuerySetAndStoreKey 342
DmQueryTemplateNames 341
DmSetKey 343
DmStartMacroEditor 344
DmStoreKey 345
DmTypeFromKeyword 346
DmUpdate 348
functions
administrative 27
attribute handling 22
audio 28
callback and dispatching 22
callbacks executed by Windows
applications 76
connection 25
database 26
querying engine parameters 101
querying value of engine parameters 114
session 26
speech engine state 27
vocabulary 27
G
grammar compiler function calls
VtAddArg 355
VtCompileGrammar 356
VtGetMessage 357
VtGetTranslation 358
VtLoadFSG 360
VtSethArg 361
VtUnloadFSG 362
H
halt recognition temporarily 81
I
improving future recognition 55
increment values, retrieving 218
initializing
speech engine, available languages 121, 123
values in a connection 89
L
languages
querying available 121, 123
languages, retrieving 220
list of alternative words, requesting 112
IBM ViaVoice SDK for Windows
M
message
cancelling request for playback 49
receiving and dispatching callbacks 76
receiving from speech engine 149
message explanations
DMAPI 425
SMAPI 379
message type, retrieving 223
message types
SMAPI 375
message word count, retrieving 225
messages
DMAPI 423
SMAPI 369
microphone
turning off 83, 161
turning on 85, 162
microphone state, retrieving 221
misrecognized word, correcting 188
N
name values, retrieving 224
naming conventions 21
next word to decode, searching 150
notification
requesting when speech engine completes
decoding 79
O
opening
SMAPI 89
options field, retrieving 226
options flags, retrieving 244
P
parallel session API calls 29
parameters
querying value of engine 114
percent complete, retrieving 227
phrase score, retrieving 228
phrase state flags, retrieving 229
playback request, cancelling 49
playing
prerecorded audio file 91
playing back
spoken utterance 94
spoken words 97
predefined vocabularies, adding words to 43
preferred topics count, retrieving 231
prerecorded audio file, playing 91
processing
recognized commands 33
recognized text 36
speech, directing engine 33, 36
pronunciation
adding new 40
querying added 127, 129
querying existence 125
removing from personal pool 157
pronunciations, retrieving 232
Q
querying
added words 107, 109
available languages 121, 123
currently enabled vocabularies 117
default values for user, enrollment, task ID 115
enroll ID 141
existence of pronunciation 125
listing of added pronunciations 127, 129
sessions 133
speech data 134
speech engine functions 27
user enrollment IDs 119
user ID 141
users allowed to use speech engine 143
vocabularies, all defined 145
querying engine parameters 101
querying parameters 101
R
reason code, retrieving 215
receiving
messages
dispatching callbacks 76
messages from speech engine 149
recognition
improving future 55
IBM SMAPI Reference
recognition session
enabling defined vocabulary 77
establishing 32, 35
querying 133
temporary halt 81
recognized
commands, processing 33
text, processing 36
releasing speech focus 152
removing
callback routine 153
pronunciation from personal pool 157
words from dynamic vocabulary 154
reply message structures 281
speech engine 281
reply structure domain, retrieving 255
reply structure functions
unsolicited callbacks 295
reply structure multiple domains, retrieving 257
reply structure tags, retrieving 254
requesting
completions of specified string 47
microphone turnoff 161
speech focus 159
resetting utterance number 163
retrieving
alphabets 193
alternative words 195
annotations 196
archive size 245
archived file name 243
array of increment values 218
audio message name 222
audio signal 200
engine state 205
enroll IDs 207, 208
enrollment IDs 203
enrollment status 251
event ID 210
firm words 212
focus state 216
languages 220
message type 223
message word count 225
microphone state 221
name of application 199
name values 224
options field 226
options flags 244
options for event 211
path name of FSG file 217
percent complete 227
phrase score 228
phrase state flags 229
preferred topics count 231
pronunciations 232
reason code for focus change 215
reply structure domain 255
reply structure multiple domains 257
reply structure tags 254
return code 233
return code description 234
return code name 235
sample rates 236
script flags 237
scripts 238
service description 239
session ID 240
severity 241
single flags 213
size values 242
spelling 247
spellings 249
start/end times 275
status 252
task information 256
time values 258
topics array 260
trained values array 261
user ID 262
user IDs 264
users 266
utterance number 267
value of item 201
values 219
version identifier 246
vocabulary list 268
vocabulary name 269
vocabulary path 271
vocabulary words 272
words 274
IBM ViaVoice SDK for Windows
return code description, retrieving 234
return code name, retrieving 235
return code, retrieving 233
return codes
DMAPI 423
SMAPI 369
returning
ASCII string 278
SM_MSG return code 277
symbolic name 279
Windows codepage 202
router
callbacks 292
router.msg log 420
S
sample rates, retrieving 236
saving current speech data 165
script flags, retrieving 237
scripts, retrieving 238
searching next word to decode 150
service description, retrieving 239
session
detaching 67
disabling a defined vocabulary 68
functions 26
querying 133
recognition
establishing 32
starting a speech engine connection 52
session ID, retrieving 240
set speech engine functions 27
setting
default values 179
files used by engine 181
user information 184
value of speech engine parameter 177
setting up
vocabularies 32, 35
severity, retrieving 241
single callback routine, adding 39
size values, retrieving 242
SM_ANNOTATION 301
SM_MSG return code, returning 277
SM_VOCWORD 302
SM_WORD 303
SmAddCallback function call 39
SmAddPronunciation function call 40
SmAddToVocab function call 43
SMAPI
administrative functions 27
attributes 305
audio functions 28
callback and dispatching functions 22
checking version 46
closing connection 51
connecting 89
connection functions 25
database functions 26
engine messages 373
engine return codes 373
establishing connection 89
function calls by group 22
message explanations 379
message types 375
messages 369
opening 89
parallel session API calls 29
return codes 369
router.msg log 420
session functions 26
status codes 374
status messages 374
vocabulary functions 27
SmApiVersionCheck function call 46
SmArg 299
SmArgVal 300
SmAutoComplete function call 47
SmCancelPlayback function call 49
SmClose function calls 51
SMCOMM.H, defined reply message
structures 281
SmConnect function calls 52
SmCorrectText function call 55
SmDefineGrammar function call 57
SmDefineVocab function call 60
SmDefineVocabEx function call 63
SmDetachSessions function call 67
SmDisableVocab function call 68
SmDiscardData function call 70
SmDiscardSpeechData function call 72
SmDisconnect function call 74
SmDispatch function call 76
IBM SMAPI Reference
SmEnableVocab function call 77
SmEventNotify function call 79
SmGetAlphabets data access function 193
SmGetAlternates data access function 195
SmGetAnnotations data access function 196
SmGetApplication data access function 198
SmGetApplications data access function 199
SmGetAudioLevel data access function 200
SmGetBinaryItemValue data access
function 201
SmGetCodePage data access function 202
SmGetDescriptions function call 203
SmGetEngineState data access function 205
SmGetEnrollId data access function 207
SmGetEnrollIds data access function 208
SmGetEventId data access function 210
SmGetEventOptions data access function 211
SmGetFirmWords data access function 212
SmGetFlags data access function 213
SmGetFocusChangeReason data access
function 215
SmGetFocusState data access function 216
SmGetGrammarPath data access function 217
SmGetIncrements data access function 218
SmGetItemValue data access function 219
SmGetLanguages data access function 220
SmGetMicState data access function 221
SmGetMsgName data access function 222
SmGetMsgType data access function 223
SmGetNameValue data access function 224
SmGetNumberWordMsgs data access
function 225
SmGetOptions data access function 226
SmGetPercentages data access function 227
SmGetPhraseScore data access function 228
SmGetPhraseState data access function 229
SmGetPreferred data access function 231
SmGetPronunciations data access
function 232
SmGetRc data access function 233
SmGetRcDescription data access function 234
SmGetRcName data access function 235
SmGetSampleRates data access function 236
SmGetScriptFlags data access function 237
SmGetScripts data access function 238
SmGetService data access function 239
SmGetSessionId data access function 240
SmGetSeverity data access function 241
SmGetSizes data access function 242
SmGetSpeechDataArchive data access
function 243
SmGetSpeechDataOptions data access
function 244
SmGetSpeechDataSize data access
function 245
SmGetSpeechDataVersion data access
function 246
SmGetSpelling data access function 247
SmGetSpellings data access function 249
SmGetStates data access function 251
SmGetStatus data access function 252
SmGetTags data access function 254
SmGetTask data access function 255
SmGetTaskFlags data access function 256
SmGetTasks data access function 257
SmGetTimes data access function 258
SmGetTopics data access function 260
SmGetTrained data access function 261
SmGetUserId data access function 262
SmGetUserIds data access function 264
SmGetUsers data access function 266
SmGetUtteranceNumber data access
function 267
SmGetVocabList data access function 268
SmGetVocabName data access function 269
SmGetVocabPath data access function 271
SmGetVocWords data access function 272
SmGetWords data access function 274
SmGetWordTimes data access function 275
SmHaltRecognizer function call 81
SmHandler 300
SmMicOff function call 83
SmMicOn function call 85
SmMsg 302
SmMsgReceive function call 149
SmNewContext function call 87
SmPlayMessage function call 91
SmPlayUtterance function call 94
SmPlayWords function calls 97
SmQuery function call 101
SmQueryAddedWord function call 107
SmQueryAddedWordsEx function call 109
SmQueryAlternates function call 112
SmQueryBinary function call 114
SmQueryDefault function call 115
SmQueryEnabledVocabs function call 117
SmQueryEnrollIds 119
SmQueryLanguages function call 121
IBM ViaVoice SDK for Windows
SmQueryPhraseAlternatives function call 123
SmQueryPronunciation function call 125
SmQueryPronunciationEx function call 129
SmQueryPronunciations function call 127
SmQueryScripts function call 131
SmQuerySessions function call 133
SmQuerySpeechData function call 134
SmQueryTasks function call 135
SmQueryTopics function call 137
SmQueryUserDefault function call 139
SmQueryUserInfo funciton call 141
SmQueryUsers function call 143
SmQueryVocabs function call 145
SmQueryWord function call 147
SmRecognizeNextWord function call 150
SmReleaseFocus function call 152
SmRemoveCallback function call 153
SmRemoveFromVocab function call 154
SmRemovePronunciation function call 157
SmRequestFocus function call 159
SmRequestMicOff function call 161
SmRequestMicOn function call 162
SmRestoreSpeechData function call 163
SmReturn data access function 277
SmReturnRcDescription data access
function 278
SmReturnRcName data access function 279
SmSaveSpeechData function call 165
SmSet function call 167
SmSetArg function call 176
SmSetBinary function call 177
SmSetDefault function call 179
SmSetDirectory function call 181
SmSetUserDefault function calls 182
SmSetUserInfo function call 184
SmUndefineVocab function call 186
SmWordCorrection function call 188
specified word, checking active vocabularies 147
speech attributes
querying default 115
speech data
querying 134
speech data, saving current 165
speech engine 101
adding new pronunciation 40
adding words to vocabulary 43
callbacks 292
changing text context sent to 87
closing connection 51
connecting to 52
disabling a defined vocabulary 68
discarding audio and error-correction data 70,
72
disconnecting 67, 74
enabling vocabulary 77
error messages 441
function calls
SmAddPronunciation 40
SmAddToVocab 43
SmApiVersionCheck 46
SmAutoComplete 47
SmCallback 39
SmCancelPlayback 49
SmClose 51
SmConnect 52
SmCorrectText 55
SmDefineGrammar 57
SmDefineVocab 60
SmDefineVocabEx 63
SmDetachSessions 67
SmDisableVocab 68
SmDiscardData 70
SmDiscardSpeechData 72
SmDisconnect 74
SmDispatch 76
SmEnableVocab 77
SmEventNotify 79
SmHaltRecognizer 81
SmMicOff 83
SmMicOn 85
SmNewContext 87
SmPlayMessage 91
SmPlayUtterance 94
SmPlayWords 97
SmQuery 101
SmQueryAddedWords 107
SmQueryAddedWordsEx 109
SmQueryAlternates 112
SmQueryBinary 114
SmQueryDefault 115
IBM SMAPI Reference
SmQueryEnabledVocabs 117
SmQueryEnrollIds 119
SmQueryLanguages 121
SmQueryPhraseAlternatives 123
SmQueryPronunciation 125
SmQueryPronunciations 127
SmQueryPronunciationsEx 129
SmQueryScripts 131
SmQuerySessions 133
SmQuerySpeechData 134
SmQueryTasks 135
SmQueryTopics 137
SmQueryUserDefault 139
SmQueryUserInfo 141
SmQueryUsers 143
SmQueryVocabs 145
SmQueryWord 147
SmReceiveMsg 149
SmRecognizeNextWord 150
SmReleaseFocus 152
SmRemoveCallback 153
SmRemoveFromVocab 154
SmRemovePronunciation 157
SmRequestFocus 159
SmRequestMicOff 161
SmRequestMicOn 162
SmRestoreSpeechData 163
SmSaveSpeechData 165
SmSet 167
SmSetArg 176
SmSetBinary 177
SmSetDefault 179
SmSetDirectory 181
SmSetUserDefault 182
SmSetUserInfo 184
SmUndefineVocab 186
SmWordCorrection 188
function calls to 39
halt recognition temporarily 81
naming conventions for IDs 21
notification when decoding complete 79
querying
default attributes 115
domain list 135, 137
querying parameters 114
receiving messages from 76
reply message structures 281
request for string completion 47
setting
files to use 181
value of parameter 177
single callback routine,adding 39
state
functions 27
retrieving 205
terminating connection 51
turning off microphone 83
turning on microphone 85
updating user’s voice model 55
speech focus
releasing 152
requesting 159
speech recognition errors
correcting 37
spelling, associating pronunciation with 40
spelling, retrieving 247
spellings, retrieving 249
spoken words, playing back 97
start/end times, retrieving 275
starter set APIs
command and control 31
dictation 34
status codes
SMAPI 374
status messages
SMAPI 374
status, retrieving 252
string functions
SmAutoComplete 47
symbolic name, returning 279
T
task information, retrieving 256
temporary halt of recognition session 81
terminating SMAPI connection 51
IBM ViaVoice SDK for Windows
text
processing recognized 36
time values, retrieving 258
topics array, retrieving 260
trained values array, retrieving 261
turning off microphone 83
turning on microphone 85
U
unlimited vocabulary dll
VtGeneratePronunciations 367
unsolicited callbacks
reply structure functions 295
updating user’s voice model 55
user
information, setting 184
querying enrollment IDs 119
user ID, retrieving 262
user IDs, retrieving 264
users, retrieving 266
utterance
cancelling request for playback 49
playing back 94
resetting number 163
utterance number, retrieving 267
V
values, retrieving 219
version identifier, retrieving 246
version, checking SMAPI and API 46
vocabularies
checking for specified word 147
querying added words 107, 109
querying currently enabled 117
setting up and enabling 32, 35
vocabulary
adding words to 43
deleting dynamic 186
disabling defined 68
dynamically creating new 60, 63
enabling defined 77
functions 27
removing words from 154
vocabulary list, retrieving 268
vocabulary name, retrieving 269
vocabulary path, retrieving 271
vocabulary words, retrieving 272
voice model, updating user’s 55
VtAddArg 355
VtArg 363
VtCompileGrammar 356
VtGeneratePronunciations 367
VtGetMessage 357
VtGetTranslation 358
VtLoadFSG 360
VtSethArg 361
VtUnloadFSG 362
W
Windows applications
executing callbacks 76
words
alternative, requesting list of 112
cancelling request for playback 49
words, retrieving 274
IBM SMAPI Reference
|
|
QQ群⑧：
窥视卡
雷达卡
发表于 2017-5-26 09:53:13
提升卡
置顶卡
沉默卡
喧嚣卡
变色卡
千斤顶
显身卡