IBM语音技术API说明，比较锻炼英文能力

nvercongming

浏览: 1108175 次

最近访客更多访客>>

potyzhang

BeyondPC

u012363178

jackuhan

博主相关

博客

微博

相册

留言

关于我

文章分类

全部博客 (1477)

社区版块

存档分类

2012-04 ( 2)
2011-12 ( 130)
2011-11 ( 350)
更多存档...

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

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

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

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

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.

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

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

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

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

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

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.

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

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.

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

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.

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.

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.

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

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.

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

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

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

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.

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

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

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

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

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.

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

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.

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

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

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

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

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

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

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

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.

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

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

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.

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.

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

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.

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

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.

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

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.

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

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.

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.

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

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

Purpose
SmQueryEnabledVocabs queries currently enabled vocabularies.
This function obtains a list of all currently enabled vocabularies.

Syntax

int SmQueryEnabledVocabs (SM_MSG *reply);

Parameters

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

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.

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

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

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

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.

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

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.

Syntax

int SmQueryPronunciation (char *spelling, SM_MSG *reply );

Parameters

spelling

input -A spelling for which a pronunciation is sought.

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

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

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

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.

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

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.

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

Purpose
SmQuerySessions queries sessions and returns a list of connected recognition sessions.

Syntax

int SmQuerySessions (SM_MSG *reply);

Parameters

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

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

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.

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

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

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

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.

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

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.

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

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

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

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

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

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.

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

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

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

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

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.

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

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.

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Purpose

SmGetRc retrieves the return code for the SMAPI functions.
Syntax

int SmGetRc (SM_MSG reply, int *rc);

Parameters

input - The reply structure from a SMAPI function.

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

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

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

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

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

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

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

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

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

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

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

Purpose

SmGetSeverity retrieves the severity associated with an unsolicited
SM_REPORT_ENGINE_ERROR message.

Syntax

int SmGetSeverity (SM_MSG reply, unsigned long *severity);

Parameters

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

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

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

input - The reply structure from a SMAPI function.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

input - Any return code associated with any Sm call.

Task Related Functions and Callbacks

SmReturnRc
SmReturnRcName

IBM ViaVoice SDK for Windows

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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:

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[i] = // 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

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.

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.

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.

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.

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

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

beginning text dictation at a new document
location 87

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

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

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

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

grammar compiler function calls
VtAddArg 355
VtCompileGrammar 356
VtGetMessage 357
VtGetTranslation 358
VtLoadFSG 360
VtSethArg 361
VtUnloadFSG 362

halt recognition temporarily 81

improving future recognition 55
increment values, retrieving 218
initializing

speech engine, available languages 121, 123
values in a connection 89

languages

querying available 121, 123
languages, retrieving 220
list of alternative words, requesting 112

IBM ViaVoice SDK for Windows

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

name values, retrieving 224
naming conventions 21
next word to decode, searching 150
notification
requesting when speech engine completes
decoding 79

opening
SMAPI 89
options field, retrieving 226
options flags, retrieving 244

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

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

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

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

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

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

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

Windows applications
executing callbacks 76

words
alternative, requesting list of 112
cancelling request for playback 49

words, retrieving 274

IBM SMAPI Reference

分享到：

使用java技术实现IBM VIAVOICE 语音朗读技 ... | 一个基于Windows Vista speech API5.3以及 ...

2008-12-13 22:26
浏览 1389
评论(0)
查看更多

发表评论

您还没有登录,请您登录后再发表评论

最近访客更多访客>>

博主相关

文章分类

社区版块

存档分类

最新评论