Application Programming Interface (API) Reference

IBM Speech API (SMAPI)

Overview

This chapter describes the format of the function calls that are presented in "Function Calls to the Engine" and "Data Access Functions". "Function Calls to the Engine" contains the function calls that go directly to the speech engine. "Data Access Functions" 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.
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 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 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 Appendix A. "SMAPI Return Codes and Messages".
Reply Structure Functions by Message Type	A list of all reply message structures that can be received from the speech 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 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 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 table, found in the file SMLIMITS.H, shows the minimum and maximum lengths of most 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
  

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 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
• SmGetApplication
• SmGetApplications
• SmGetAudioLevel
• SmGetDescriptions
• SmGetEngineState
• SmGetEnrollId
• SmGetEnrollIds
• SmGetEventId
• SmGetEventOptions
• SmGetFirmWords
• SmGetFocusState
• SmGetInfirmWords
• SmGetItemValue
• SmGetLanguages
• SmGetMicState
• SmGetMsgName
• SmGetMsgType
• SmGetNameValue
• SmGetNumberWordMsgs
• SmGetPercentages
• SmGetPronunciations
• SmGetRc
• SmGetRcDescription
• SmGetRcName
• SmGetScripts
• SmGetService
• SmGetSessionId
• SmGetSeverity
• SmGetSpelling
• SmGetSpellings
• SmGetStates
• SmGetStatus
• SmGetTags
• SmGetTask
• SmGetTasks
• SmGetTimes
• SmGetUserId
• SmGetUserIds
• SmGetUsers
• SmGetUtteranceNumber
• SmGetVocabList
• SmGetVocabName
• SmGetVocWords
• SmGetWords
• SmReturnRc
• SmReturnRcDescription
• SmReturnRcName

Connection Functions

These functions enable an application to connect to, or disconnect from, the speech engine. They are permitted at any time.

• SmApiVersionCheck
• SmClose
• SmConnect
• SmDisconnect
• SmOpen

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 engine. Consequently, they are permitted at any time. Some returned information pertains to a specific session; some pertains to the speech engine as a whole.

• SmQueryAddedWords
• SmQueryAlternates
• SmQueryDefaults
• SmQueryEnabledVocabs
• SmQueryEnrollIds
• SmQueryLanguages
• SmQueryPronunciation
• SmQueryPronunciations
• SmQuerySessions
• SmQueryTasks
• SmQueryUserInfo
• SmQueryUsers
• SmQueryVocabs
• SmQueryWord

The following functions are administrative. They do not change the state of the engine for the application with focus:

• SmSetDefault
• SmSetUserInfo

Speech Engine State Functions

These functions set and query the state of the speech engine.

• SmSet
• SmQuery

Vocabulary Functions

These functions change the state of the active, dynamically desired vocabularies, and they are handled independently for each session. They are transparent to the application.

• SmAddPronunciation
• SmAddToVocab
• SmCorrectText
• SmCorrectTextCancel
• SmDefineVocab
• SmDisableVocab
• 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

Parallel Session API Calls

The ability to have more than one connection to the engine 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.