# Application Programming Interface (API) Reference

# Function Calls to the Engine

This chapter lists and describes the function calls that go directly to the speech 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

## 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. Refer to SmSet 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.

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.

  - SM_ADD_PRONUNCIATION_PHONETIC - Add a phonetic pronunciation.

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
    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

## 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 engine is not decoding speech to text.

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.

vocwords

  input - The spellings of the words added to the vocabulary.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous, indicating that the call is made asynchronously.

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
    SmNaddToVocabCallback
    SmNdefineVocabCallback
    SmNdisableVocabCallback
    SmNenableVocabCallback
    SmNqueryAddedWordsCallback
    SmNqueryEnabledVocabsCallback
    SmNqueryVocabsCallback
    SmNqueryWordsCallback
    SmNremoveFromVocabCallback
    SmNundefineVocabCallback

## 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

## SmCancelPlayback

Purpose

SmCancelPlayback cancels the request to play back a message, utterance, or words.

This function cancels a play request from the SmPlayMessage, SmPlayUtterance, and SmPlayWords functions.

Syntax

    int SmCancelPlayback(SM_MSG *reply);

Parameters

reply

  input/output - The pointer to a reply structure or to SmAsynchronous, indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK

    For synchronous call and callbacks:
    SM_RC_NOT_VALID_REQUEST

Reply Structure Functions by Message Type

SM_CANCEL_PLAYBACK_REPLY

- SmGetRc

Task Related Functions and Callbacks

    SmPlayMessage
    SmPlayUtterance
    SmPlayWords
    SmNcancelPlaybackCallback
    SmNplayMessageCallback
    SmNplayMessageStatusCallback
    SmNplayUtteranceCallback
    SmNplayUtteranceStatusCallback
    SmNplayWordsCallback
    SmNplayWordsStatusCallback

## 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 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

## SmConnect

Purpose

SmConnect connects to the speech engine.

This function establishes a session with the speech 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 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 the attributes, see "SMAPI Attributes".

reply

  input - The pointer to a reply structure or to SmAsynchronous, indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_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

Reply Structure Functions by Message Type

SM_CONNECT_REPLY

- SmGetMsgType
- SmGetRc
- SmGetService
- SmGetSessionId
- SmGetTask
- SmGetTasks
- SmGetUserId

Only recognition sessions:

- SmGetEnrollId
- SmGetEnrollIds
- SmGetLanguages
- SmGetSessionId
- SmGetUserId
- SmGetUserIds

Task Related Functions and Callbacks

    SmOpen
    SmSetArg
    SmNconnectCallback

## SmCorrectText

Purpose

SmCorrectText updates the user's voice model with a sequence of text the user considers correct.

This function provides the speech engine with a sequence of correctly recognized text. This text can be used to adapt the user's voice model, thereby improving future recognition of dictated text.

Syntax

    int SmCorrectText (short    nwords,
                       SM_WORD *words[],
                       SM_MSG  *reply);

Parameters

nwords

  input - The number of words in the text sequence.

words

  input - An array of pointers to the words of the text.

reply

  input/output - The pointer to a reply structure indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_INVALID_PARM_MAX_LEN
     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

    SmCorrectTextCancel
    SmNewContext
    SmRemovePronunciation
    SmWordCorrection
    SmNcorrectTextCallback
    SmNcorrectTextCancelCallback
    SmNnewContextCallback
    SmNremovePronunciationCallback
    SmNwordCorrectionCallback

## SmCorrectTextCancel

Purpose

SmCorrectTextCancel cancels the previous notification of a correct sequence of text.

This function undoes the previous call to SmCorrectText.

Syntax

    int SmCorrectTextCancel (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to a reply structure or to SmAsynchronous, indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK

    For synchronous call and callbacks:
    SM_RC_NOT_VALID_REQUEST

Reply Structure Functions by Message Type

SM_CORRECT_TEXT_CANCEL_REPLY

- SmGetRc

Task Related Functions and Callbacks

    SmCorrectText
    SmNewContext
    SmRemovePronunciation
    SmWordCorrection
    SmNcorrectTextCallback
    SmNcorrectTextCancelCallback
    SmNnewContextCallback
    SmNremovePronunciationCallback
    SmNwordCorrectionCallback

## 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 or the base domain pool.

Syntax

    int SmDefineGrammar (char       *vocab,
                         char       *grammar,
                         long        options,
                         SM_MSG     *reply);

Parameters

vocab

  input - The name of the new grammar.

grammar

  input - The fully qualified pathname of the .FSG file contaning 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 runtime flags override settings compiled in the .FSG file.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous, indicating that the call is made asynchronously.

Return Values

    SM_RC_OK
    SM_RC_MISSING_EXTERN
    SM_RC_NOT_VALID_REQUEST
    SM_RC_NOT_INVOCAB
    SM_RC_BAD_VOCAB
    SM_RC_SERVER_FILE_MALLOC_ERROR
    SM_RC_SERVER_FILE_OPEN_ERROR
    SM_RC_SERVER_FILE_READ_ERROR

Reply Structure Functions by Message Type

SM_DEFINE_GRAMMAR_REPLY

- SmNdefineGrammarCallback
- SmGetVocabName
- SmGetGrammarPath
- SmGetVocWords

Task Related Functions and Callbacks

    SmEnableVocab
    SmGetAnnotations
    SmUndefineGrammar
    SmDisableVocab
    SmNdisableVocabCallback
    SmNdenableVocabCallback
    SmNundefineVocabCallback

## 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 engine is not decoding speech to text.

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.

vocwords

  input - The spellings of the words in the new vocabulary.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous, indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_INVALID_PARM_MAX_LEN

    For synchronous call and callbacks:
    SM_RC_BAD_VOCAB
    SM_RC_NOT_VALID_REQUEST
    SM_RC_SERVER_FILE_OPEN_ERROR
    SM_RC_SERVER_FILE_WRITE_ERROR

Reply Structure Functions by Message Type

SM_DEFINE_VOCAB_REPLY

- SmGetRc
- SmGetVocabName
- SmGetVocWords

Task Related Functions and Callbacks

    SmAddToVocab
    SmDisableVocab
    SmEnableVocab
    SmQueryAddedWords
    SmQueryEnabledVocabs
    SmQueryVocabs
    SmQueryWord
    SmRemoveFromVocab
    SmUndefineVocab
    SmNaddToVocabCallback
    SmNdefineVocabCallback
    SmNdisableVocabCallback
    SmNenableVocabCallback
    SmNqueryAddedWordsCallback
    SmNqueryEnabledVocabsCallback
    SmNqueryVocabsCallback
    SmNqueryWordsCallback
    SmNremoveFromVocabCallback
    SmNundefineVocabCallback

## SmDetachSessions

Purpose

SmDetachSessions requests that one or more sessions detach.

This function requests all applications connected to the speech 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 userid, enrollid, task).

Syntax

    int SmDetachSessions (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to a reply structure or to SmAsynchronous, indicating that the call is made asynchronously.

Return Values

    SM_RC_OK

Reply Structure Functions by Message Type

SM_DETACH_SESSIONS_REPLY

- SmGetRc

Task Related Functions and Callbacks

    SmQuerySessions
    SmNdetachRequestedCallback
    SmNdetachSessionsCallback
    SmNquerySessionsCallback

## SmDisableVocab

Purpose

SmDisableVocab disables a defined vocabulary.

This function disables a vocabulary so it is no longer used by the speech 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 engine is not decoding speech to text.

Syntax

    int SmDisableVocab (char   *vocab,
                        SM_MSG *reply);

Parameters

vocab

  input - The name of the vocabulary to be disabled.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous, indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_INVALID_PARM_MAX_LEN

    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

## 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 engine disk space (refer to the SmNdiscardSessionData speech attribute used at SmDisconnect).

SmDiscardData works on the granularity of utterances (between SmMicOn and SmMicOff) and discards utterance files owned by the application. Ownership is established by the application that turned the microphone on to create the utterance. An application can guarantee ownership of its data by toggling the microphone Off and On when it receives focus.

Syntax

    int SmDiscardData (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to a reply structure or to SmAsynchronous, indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK

    For synchronous call and callbacks:
    SM_RC_NOT_VALID_REQUEST

Reply Structure Functions by Message Type

SM_DISCARD_DATA_REPLY

- SmGetRc

Task Related Functions and Callbacks

## SmDisconnect

Purpose

SmDisconnect disconnects from the speech engine.

This function closes the communication connection with the speech engine.

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 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)

reply

  input/output - The pointer to a reply structure or to SmAsynchronous, indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK

    For synchronous call and callbacks:
    SM_RC_BAD_ENROLLID
    SM_BAD_SCRIPT
    SM_RC_BAD_VALUE
    SM_RC_ENROLLID_EXISTS
    SM_RC_ENROLLID_RUNNING
    SM_RC_NO_SPACE_TERM_ENROLL
    SM_RC_NOT_VALID_REQUEST
    SM_RC_SERVER_ERROR

Reply Structure Functions by Message Type

SM_DISCONNECT_REPLY

- SmGetMsgType
- SmGetRc
- SmGetService

Task Related Functions and Callbacks

    SmClose
    SmNdisconnectCallback

## SmDispatch

Purpose

SmDispatch receives one message and dispatches the callbacks.

This function provides the method through which callback functions are executed by OS/2 applications. More specifically, this function receives one message from the speech 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 - OS/2 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

## SmEnableVocab

Purpose

SmEnableVocab enables a defined vocabulary.

This function enables a vocabulary to be used by the speech 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 engine is not decoding speech to text.

Syntax

    int SmEnableVocab (char   *vocab,
                       SM_MSG *reply);

Parameters

vocab

  input - The name of the vocabulary to be enabled.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous, indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_INVALID_PARM_MAX_LEN

    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

## SmEventNotify

Purpose

SmEventNotify requests notification when the speech engine completes decoding all the audio dictated up to the time SmEventNotify was called.

This function causes the callback associated with the SmNaudioEventCallback attribute 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 engine.

Syntax

    int SmEventNotify (long    event_id,
                       long    options,
                       SM_MSG *reply);

Parameters

event_id

  input - The event ID.

options

  input - The options for the event, which can be logically OR'ed:

  - SM_EVENT_HALT_RECOGNITION - halt and switch to command recognition when event is encountered (Default)

  - SM_EVENT_CONTINUE_RECOGNITION - notify application that event was encountered and continue with recognition

  - SM_EVENT_FIRM_UP - process audio following event

  - SM_EVENT_DISCARD - discard audio following event (Default)

  Notes:

  - SM_EVENT_HALT_RECOGNITION and SM_EVENT_CONTINUE_RECOGNITION cannot be specified together.

  - SM_EVENT_FIRM_UP and SM_EVENT_DISCARD cannot be specified together.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous, indicating that the call is made asynchronously.

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

## SmHaltRecognizer

Purpose

SmHaltRecognizer temporarily halts recognition.

This function can be called when the speech engine is decoding speech to text. Halting recognition may be necessary, for example, to define and/or enable vocabularies to be used by the engine during recognition. Recognition can be restarted with SmRecognizeNextWord.

Syntax

    int SmHaltRecognizer (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to the reply structure or to the SmAsynchronous value.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK

    For synchronous call and callbacks:
    SM_RC_NOT_VALID_REQUEST
    SM_RC_SERVER_ERROR

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

## 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 engine continues speech to text decoding of words already spoken. Depending on the speed and what is said before the microphone is turned off, this process can take several seconds to complete.

Syntax

    int SmMicOff (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to a reply structure or to SmAsynchronous, indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK

    For synchronous call and callbacks:
    SM_RC_MIC_ALREADY_OFF
    SM_RC_MIC_OFF_PENDING
    SM_RC_NOT_VALID_REQUEST

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

## SmMicOn

Purpose

SmMicOn turns on the microphone.

In a recognition session, this function turns on the microphone and starts the audio stream. The application must issue an SmRecognizedNextWord to start the engine decoding.

Syntax

    int SmMicOn (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to the reply structure or to the SmAsynchronous value.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_INVALID_PARM_MAX_LEN

    For synchronous call and callbacks:
    SM_RC_BAD_AP
    SM_RC_BAD_DECO
    SM_RC_BUSY_LAST_UTTERANCE
    SM_RC_BUSY_WORD_CORRECTION
    SM_RC_ENROLLMENT_NOT_COMPLETE
    SM_RC_MIC_ALREADY_ON
    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

## SmNewContext

Purpose

SmNewContext sends a new text context.

This function allows a change in text context sent to the speech 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 engine is halted. Context refers to previous and following words, which are used to decode the current word in a recognition session.

Syntax

    int SmNewContext (short          nwords,
                      SM_WORD       *words[],
                      SM_MSG        *reply);

Parameters

nwords

  input - The number of words of context sent. Zero means no left context.

words

  input - An array of pointers to the context words, ordered from left to right in the text.

reply

  input/output - The pointer to the reply structure or to the SmAsynchronous value indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_INVALID_PARM_MAX_LEN

    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

## 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 engine. Speech API attributes can also be set by using the SmSetArg function, which specifies the attribute name and its value.

  For details on the attributes, see "SMAPI Attributes".

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

Task Related Functions and Callbacks

    SmConnect
    SmSetArg
    SmNconnectCallback

## 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 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 VoiceType format, which is 8-bit (mono) u-Law PCM at 11.025kHz. These audio files can be created by dictating the message and saving to a file in IBM VoiceType Dictation. (Ref #1.)

language

  input - The name of the language played.

reply

  input/output - The pointer to the reply structure or to the SmAsynchronous value indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_INVALID_PARM_MAX_LEN

    For synchronous call and callbacks:
    SM_RC_BAD_LANGUAGE
    SM_RC_BAD_MESSAGE
    SM_RC_NOT_VALID_REQUEST
    SM_RC_NOT_WHILE_MIC_ON

Reply Structure Functions by Message Type

SM_PLAY_MESSAGE_REPLY

- SmGetRc

SM_PLAY_MESSAGE_STATUS

- SmGetMsgName
- SmGetRc
- SmGetStatus

Task Related Functions and Callbacks

    SmCancelPlayback
    SmPlayUtterance
    SmPlayWords
    SmNcancelPlaybackCallback
    SmNplayMessageCallback
    SmNplayMessageStatusCallback
    SmNplayUtteranceCallback
    SmNplayUtteranceStatusCallback
    SmNplayWordsCallback
    SmNplayWordsStatusCallback

## 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 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).

Syntax

    int SmPlayUtterance (long    uttno,
                         long    begtime,
                         long    endtime,
                         SM_MSG *reply);

Parameters

uttno

  input - The utterance number to play back. The current utterance number can be extracted from SM_MIC_ON_REPLY with SmGetUtteranceNumber.

begtime

  input - Reserved. Must be set to 0.

endtime

  input - Reserved. Must be set to 0.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous, indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK

    For synchronous call and callbacks:
    SM_RC_NOT_VALID_REQUEST
    SM_RC_NOT_WHILE_MIC_ON

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

## 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.

After the speech-aware application requests a playback, it can then 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_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

During a monitored enrollment session, the words that can be played back are those belonging to the example recording of an enrollment script. These words are retrieved by using the SmRequestScriptText call. During a recognition session, the words that can be played back are those found in the reply message structures, SM_RECOGNIZED_TEXT and SM_RECOGNIZED_WORD, sent by the speech engine.

The following restrictions apply when calling SmPlayWords:

- Microphone must be off.
- Speech 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).

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 after all words are played. This is the default.
  SM_PLAY_WORDS_SEPARATE | Reserved, not supported.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous, indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_INVALID_PARM_MAX_LEN

    For synchronous call and callbacks:
    SM_RC_BAD_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
    SmNplayMessageStatusCallback
    SmNplayUtteranceCallback
    SmNplayUtteranceStatusCallback
    SmNplayWordsCallback
    SmNplayWordsStatusCallback
    SmNqueryAddedWordsCallback

## SmQuery

Purpose

SmQuery queries a speech engine parameter.

This function queries the value of the specified speech 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 | Query the input source of the audio hardware where audio data is collected. The returned value is bit mapped and can be any combination of the following values: SM_AUDIO_INPUT_MIC_HI_GAIN SM_AUDIO_INPUT_MIC_LO_GAIN SM_AUDIO_INPUT_LINE_LEFT SM_AUDIO_INPUT_LINE_RIGHT SM_AUDIO_INPUT_VARIABLE_GAIN SM_AUDIO_OUTPUT_LINE_LEFT SM_AUDIO_OUTPUT_LINE_RIGHT SM_AUDIO_OUTPUT_INTERNAL_SPEAKER SM_AUDIO_OUTPUT_VARIABLE_GAIN Refer to the SMLIMITS.H file for bounds on input and output values.
  SM_AUDIO_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_LEVEL | Query the returning of audio-level data during recognition or enrollment. The value is either TRUE (1) or FALSE (0).
  SM_AUDIO_INPUT_MODE | Query the input source of the audio hardware where audio data is collected. 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 | If supported by underlying audio, this parameter allows you to query current gain setting.
  SM_AUDIO_OUTPUT_GAIN | If supported by underlying audio, this parameter allows you to query current gain setting.
  SM_AUDIO_OUTPUT_MODE | If supported by underlying audio, this bit value indicates the current output destination. 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_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. Values include the following: 0 is disabled, greater than 0 provides progressively more information.
  SM_ENGINE_DISPLAY | Reserved. Values include the following: 0 is disabled, greater than 0 provides progressively more information.
  SM_REJECTION_THRESHOLD | Returns value from SM_MIN_REJECTION_THRESHOLD to SM_MAX_REJECTION_THRESHOLD (refer to SmSet for a detailed description of the SM_REJECTION_THRESHOLD parameter).
  SM_ENGINE_LOG | Reserved. Values include the following: 0 is disabled, greater than 0 provides progressively more information.
  SM_NOTIFY_AUDIO_LEVEL | Query the returning of audio-level data during recognition or enrollment. The value is either TRUE (1) or FALSE (0).
  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 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_REDUCED_CPU_MODE | Query the CPU mode of the speech engine. The value is either TRUE (1) for reduced CPU mode, or FALSE (0) for normal CPU mode. See SmGetEngineState for more information.
  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. Values include the following: 0 is disabled, greater than 0 provides progressively more information.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_BAD_MODE
    SM_RC_NOT_YET
    SM_RC_EXISTS_IN_NOTIFY
    SM_RC_NOT_IN_NOTIFY

    For synchronous call and callbacks:
    SM_RC_NOT_VALID_REQUEST

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

## SmQueryAddedWords

Purpose

SmQueryAddedWords queries added words.

This function requests a list of all words that have been added to vocabularies of the currently active session.

Syntax

    int SmQueryAddedWords (char   *vocab,
                           SM_MSG *reply);

Parameters

vocab

  input - The name of the vocabulary to query.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_INVALID_PARM_MAX_LEN

    For synchronous call and callbacks:
    SM_RC_BAD_VOCAB
    SM_RC_NOT_VALID_REQUEST

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

## 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 engine must not be decoding speech to text. In other words, the application must have received SM_UTTERANCE_COMPLETED from the engine.
- SM_SAVE_AUDIO must be enabled with SmSet.

Note: For this call to be valid, the application must first enable audio saving through SmSet(SM_SAVE_AUDIO, TRUE).

Syntax

    int SmQueryAlternates (short   ntags,
                           long    tags[],
                           SM_MSG *reply);

Parameters

ntags

  input - The number of words (tags) for which alternatives are requested.

tags

  input - The tags of the word for which alternatives are requested.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

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

## SmQueryDefault

Purpose

SmQueryDefault queries the default value for a user, enrollment, or task ID speech attribute.

This function queries the value of SmNuserId, SmNenrollId, or SmNtask speech attributes. These attributes can be specified with SmOpen and SmConnect.

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

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_OK

Reply Structure Functions by Message Type

SM_QUERY_DEFAULT_REPLY

- SmGetEnrollId
- SmGetEnrollIds
- SmGetRc
- SmGetScripts
- SmGetTask
- SmGetTasks
- SmGetUserId
- SmGetUserIds

Task Related Functions and Callbacks

    SmConnect
    SmOpen
    SmSetDefault

## SmQueryEnabledVocabs

Purpose

SmQueryEnabledVocabs queries currently enabled vocabularies.

This function obtains a list of all currently enabled vocabularies.

Syntax

    int SmQueryEnabledVocabs (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK

    For synchronous call and callbacks:
    SM_RC_NOT_VALID_REQUEST

Reply Structure Functions by Message Type

SM_QUERY_ENABLED_VOCABS_REPLY

- SmGetRc
- SmGetVocabList

Task Related Functions and Callbacks

    SmAddToVocab
    SmDefineVocab
    SmDisableVocab
    SmEnableVocab
    SmQueryAddedWords
    SmQueryVocabs
    SmQueryWord
    SmRemoveFromVocab
    SmUndefineVocab
    SmNaddToVocabCallback
    SmNdefineVocabCallback
    SmNdisableVocabCallback
    SmNenableVocabCallback
    SmNqueryAddedWordsCallback
    SmNqueryEnabledVocabsCallback
    SmNqueryVocabsCallback
    SmNqueryWordsCallback
    SmNremoveFromVocabCallback
    SmNundefineVocabCallback

## 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.

Syntax

    int SmQueryEnrollIds (char   *user_id,
                          char   *enroll_id,
                          char   *language,
                          SM_MSG *reply);

Parameters

user_id

  input - The name of the user whose enrollment ID list is to be returned.

enroll_id

  input - The enrollment ID queried, or NULL if all enrollments are queried.

language

  input - The language for the enrollment ID, or NULL if all languages are queried.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    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
- SmGetScripts
- SmGetStates

Task Related Functions and Callbacks

    SmNrequestNewEnrollIdCallback

## SmQueryLanguages

Purpose

SmQueryLanguages queries the available languages.

This function returns a list of available languages that can be used to initialize the speech engine.

Syntax

    int SmQueryLanguages (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_SERVER_MALLOC_ERROR

Reply Structure Functions by Message Type

SM_QUERY_LANGUAGES_REPLY

- SmGetDescriptions
- SmGetLanguages
- SmGetRc

Task Related Functions and Callbacks

    SmNqueryLanguagesCallback

## SmQueryPronunciation

Purpose

SmQueryPronunciation queries 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 for the current session.

Syntax

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

Parameters

spelling

  input - A spelling for which a pronunciation is sought.

reply

  input/output - A pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

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

## SmQueryPronunciations

Purpose

SmQueryPronunciations queries added pronunciations.

This function requests a list of word pronunciations that have been added to the user's pronunciation pool for the current session.

Syntax

    int SmQueryPronunciations (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK

    For synchronous call and callbacks:
    SM_RC_NOT_VALID_REQUEST
    SM_RC_SERVER_ERROR
    SM_RC_SERVER_FILE_OPEN_ERROR

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

## SmQuerySessions

Purpose

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

Syntax

    int SmQuerySessions (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_OK

Reply Structure Functions by Message Type

SM_QUERY_SESSIONS_REPLY

- SmGetApplications
- SmGetEnrollIds
- SmGetRc
- SmGetTasks
- SmGetUserIds

Task Related Functions and Callbacks

    SmDetachSessions
    SmNdetachSessionsCallback
    SmNquerySessionsCallback

## SmQuerySpeechData

Purpose

SmQuerySpeechData queries speech data.

Syntax

    int SmQuerySpeechData (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_OK

Reply Structure Functions by Message Type

SM_QUERY_SPEECH_DATA_REPLY

- SmGetSpeechDataSize

## SmQueryTasks

Purpose

SmQueryTasks queries a speech 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 engine is initialized for a user.

Syntax

    int SmQueryTasks (char   *language,
                      SM_MSG *reply);

Parameters

language

  input - The language used for the domain. If specified as NULL, all domains are returned, regardless of language.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_INVALID_PARM_MAX_LEN

    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

## SmQueryUserInfo

Purpose

SmQueryUserInfo queries user ID or enrollment ID information.

This function retrieves all information associated with a user ID or an enrollment ID. Only one value can be queried at a time.

Syntax

    int SmQueryUserInfo (char   *user_id,
                         char   *enroll_id,
                         char   *itemname,
                         SM_MSG *reply);

Parameters

user_id

  input - The name of the user whose information is retrieved.

enroll_id

  input - The enrollment ID of the user whose information is retrieved. This parameter is NULL if information on the user ID is retrieved.

itemname

  input - The queried item name. The special predefined itemname parameter, SM_USER_DIRECTORY, returns the full path of the location where user files are stored. An application can store its files in the same location.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    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

## SmQueryUsers

Purpose

SmQueryUsers queries a user list.

This function returns a list of users allowed to use the speech engine. To establish a speech session, a user from this list must be supplied in the SmNuserId speech attribute.

Syntax

    int SmQueryUsers (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_SERVER_MALLOC_ERROR

Reply Structure Functions by Message Type

SM_QUERY_USERS_REPLY

- SmGetAlphabets
- SmGetDescriptions
- SmGetRc
- SmGetUserIds
- SmGetUsers

Task Related Functions and Callbacks

    SmQueryUserInfo
    SmSetUserInfo
    SmNqueryUsersCallback
    SmNqueryUserInfoCallback
    SmNsetUserInfoCallback

## SmQueryVocabs

Purpose

SmQueryVocabs queries currently defined vocabularies.

This function obtains the list of all defined speech engine vocabularies that belong to the current session. This includes predefined vocabularies and those defined after initialization with the SmDefineVocab function.

Syntax

    int SmQueryVocabs (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK

    For synchronous call and callbacks:
    SM_RC_NOT_VALID_REQUEST

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

## SmQueryWord

Purpose

SmQueryWord checks for a specified word in all active vocabularies.

Syntax

    int SmQueryWord (SM_WORD *word,
                     SM_MSG  *reply);

Parameters

word

  input - The queried word.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_INVALID_PARM_MAX_LEN

    For synchronous call and callbacks:
    SM_RC_NOT_INVOCAB

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

## SmReceiveMsg

Purpose

SmReceiveMsg receives a message from the speech engine.

This function provides the method through which speech-aware OS/2 applications receive asynchronous messages, including unsolicited asynchronous messages such as SM_RECOGNIZED_TEXT, from the speech engine. This function receives one complete message from the speech engine.

Syntax

    int SmReceiveMsg (unsigned long ap_val,
                      SM_MSG       *msg);

Parameters

ap_val

  input - For OS/2 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

## SmRecognizeNextWord

Purpose

SmRecognizeNextWord enables the recognition of the next word.

This function searches for the next word to decode. When running, the engine searches the currently enabled vocabularies to find a word that matches the incoming speech. The vocabulary that contains the best match determines what happens next:

- If the matching word comes from a dictation vocabulary, the engine sends the firm and infirm words to the application in an SM_RECOGNIZED_TEXT message and continues decoding.

- If the matching word comes from a command vocabulary, the engine sends the word and some alternative choices to the application in an SM_RECOGNIZED WORD message. The engine then halts and waits for the application to request another word.

If a recognized word occurs in two or more vocabularies enabled at the same time, the engine selects the word from the more recently enabled command vocabulary. Command vocabularies always override dictation vocabularies; when a recognized word occurs in both a command and dictation vocabulary enabled at the same time, the engine selects the command-vocabulary word.

Syntax

    int SmRecognizeNextWord (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to the reply structure or to the SmAsynchronous value indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    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

## SmReleaseFocus

Purpose

SmReleaseFocus releases speech focus.

This function releases speech focus for the application calling this API. If the application does not have the speech focus, this function returns SM_RC_NOT_VALID_REQUEST; otherwise it returns SM_RC_OK.

If the call is made asynchronously the reply can be dispatched through either of the following:

- SM_RELEASE_FOCUS
- SmNreleaseFocusCallback

Syntax

    int SmReleaseFocus (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_NOT_VALID_REQUEST
    SM_RC_OK

Reply Structure Functions by Message Type

SM_RELEASE_FOCUS

- SmGetRc

SM_FOCUS_LOST

Task Related Functions and Callbacks

    SmRequestFocus
    SmNfocusGrantedCallback
    SmNfocusRequestedCallback
    SmNreleaseFocusCallback
    SmNrequestFocusCallback

## 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

## 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 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.

vocwords

  input - The spellings of the words removed from the vocabulary.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

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
    SmNdefineVocabCallback
    SmNdisableVocabCallback
    SmNenableVocabCallback
    SmNqueryAddedWordsCallback
    SmNqueryEnabledVocabsCallback
    SmNqueryVocabsCallback
    SmNqueryWordsCallback
    SmNremoveFromVocabCallback
    SmNundefineVocabCallback

## SmRemovePronunciation

Purpose

SmRemovePronunciation removes a pronunciation from the user's personal pronunciation pool.

Syntax

    int SmRemovePronunciation (char   *spelling,
                               char   *pronunciation,
                               SM_MSG *reply);

Parameters

spelling

  input - The word spelling which references the pronunciation.

pronunciation

  input - NULL (reserved).

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_INVALID_PARM_MAX_LEN

    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

## SmRequestFocus

Purpose

SmRequestFocus requests speech focus.

An application requests speech focus with a SmRequestFocus function call. If the call is made asynchronously, the reply can be dispatched through either of the following:

- SM_REQUEST_FOCUS
- SmNrequestFocusCallback

If the request is accepted, an asynchronous message is sent after the engine grants focus. This event can be dispatched through either of the following:

- SM_FOCUS_GRANTED
- SmNfocusGrantedCallback

Important notes on return code values include the following:

- SM_RC_FOCUS_DENIED means the application with speech focus has grabbed the focus and changes are blocked by the engine.
- SM_RC_FOCUS_GRANTED means the requesting application had previously been granted speech focus and no asynchronous notification message is generated by the engine.

Syntax

    int SmRequestFocus (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_FOCUS_DENIED
    SM_RC_FOCUS_GRANTED
    SM_RC_OK

Reply Structure Functions by Message Type

SM_REQUEST_FOCUS

- SmGetRc

SM_FOCUS_GRANTED

Task Related Functions and Callbacks

    SmReleaseFocus
    SmNfocusGrantedCallback
    SmNfocusRequestedCallback
    SmNreleaseFocusCallback
    SmNrequestFocusCallback

## SmRequestMicOff

Purpose

SmRequestMicOff requests that the microphone be turned off.

This function requests the speech engine to request the application with speech focus to turn off the microphone. If no application has speech focus, then SM_RC_NO_FOCUS_APP is returned.

Syntax

    int SmRequestMicOff (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_NO_FOCUS_APP
    SM_RC_OK

Reply Structure Functions by Message Type

SM_REQUEST_MIC_OFF_REPLY

- SmGetRc

SM_REQUEST_MIC_OFF

Task Related Functions and Callbacks

    SmRequestMicOn
    SmNrequestMicOffCallback
    SmNrequestMicOnCallback

## SmRequestMicOn

Purpose

SmRequestMicOn requests that the microphone be turned on.

This function requests the speech engine to request the application with speech focus to turn on the microphone. If no application has speech focus, then SM_RC_NO_FOCUS_APP is returned.

Syntax

    int SmRequestMicOn (SM_MSG *reply);

Parameters

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_NO_FOCUS_APP
    SM_RC_OK

Reply Structure Functions by Message Type

SM_REQUEST_MIC_ON_REPLY

- SmGetRc

SM_REQUEST_MIC_ON

Task Related Functions and Callbacks

    SmRequestMicOff
    SmNrequestMicOffCallback
    SmNrequestMicOnCallback

## SmRestoreSpeechData

Purpose

SmRestoreSpeechData overwrites the current session files and resets the running utterance number. 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).

Syntax

    int SmRestoreSpeechData (char      *archive,
                             long       version,
                             SM_MSG    *reply);

Parameters

archive

  input - Filename specified on SmSaveSpeechData.

version

  input - Value defined by the application at save time and checked by the engine when the session is restored.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_OK

Reply Structure Functions by Message Type

SM_RESTORE_SPEECH_DATA_REPLY

- SmGetSpeechDataArchive
- SmGetSpeechDataSize
- SmGetSpeechDataVersion

Task Related Functions and Callbacks

    SmSaveSpeechData

## SmSaveSpeechData

Purpose

SmSaveSpeechData saves current session speech data to a file.

Note: For this call to be valid, the application must first enable audio saving through SmSet(SM_SAVE_AUDIO, TRUE).

Syntax

    int SmSaveSpeechData (char      *archive,
                             long    version,
                             long    flags,
                             SM_MSG    *reply);

Parameters

archive

  input - Filename where data will be stored.

version

  input - Identifies the data file.

flags

  input - Identifies how the data should be saved, using one of the following values:

  SM_NORMAL_FILE | The speech data is written to the file specified by the file name. This file will contain only engine data.
  SM_COMPOUND_FILE | The speech data is written to the OS/2 compound file specified by the file name, using IStorage/IStream. The data is saved in a section named "VTDSessionArchive." This allows an application to save both engine state and application state data in the same file.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_OK

Reply Structure Functions by Message Type

SM_SAVE_SPEECH_DATA_REPLY

- SmGetSpeechDataArchive
- SmGetSpeechDataOptions
- SmGetSpeechDataSize
- SmGetSpeechDataVersion

Task Related Functions and Callbacks

    SmRestoreSpeechData

## SmSet

Purpose

SmSet sets the value of a specified speech engine parameter.

Syntax

    int SmSet (short   item,
               long    value,
               SM_MSG *reply);

Parameters

item

  input - The parameter set, which can be any one of the following:

  SM_API_DEBUG | Values that can be set include the following: 0 is debugging off, 1 to 5 provide progressively more debug information. A value of 1 or 2 provides flow of control information.
  SM_API_DISPLAY | Reserved.
  SM_API_LOG | The values are: 0=Off 1=Message headers 2=Message headers + content 3=Message headers + content + internal engine messages Values above 3 are reserved.
  SM_API_TIMING | Reserved.
  SM_AUDIO_DEVICE | Selects the type of audio hardware.
  SM_AVAILABLE_AUDIO_DEVICES |
  SM_AUDIO_CONFIGURATION |
  SM_AUDIO_INPUT_LEVEL | Sets the returning of audio-level data during recognition or enrollment. The value is either TRUE (1) or FALSE (0).
  SM_AUDIO_INPUT_MODE | Sets the input source of the audio hardware where audio data is collected. Only one value can be specified per call and values include the following: SM_AUDIO_INPUT_LINE_LEFT SM_AUDIO_INPUT_LINE_RIGHT SM_AUDIO_INPUT_MIC_HI_GAIN SM_AUDIO_INPUT_MIC_LO_GAIN
  SM_AUDIO_OUTPUT_MODE | If supported by the underlying audio, this parameter indicates the current output destination. Only one value can be specified per call and values include the following: SM_AUDIO_OUTPUT_LINE_LEFT SM_AUDIO_OUTPUT_LINE_RIGHT SM_AUDIO_OUTPUT_INTERNAL_SPEAKER
  SM_AUDIO_INPUT_GAIN | If suported by underlying audio, this parameter allows you to set current gain setting. Refer to the SMLIMITS.H file for bounds on intput and output values.
  SM_AUDIO_OUTPUT_GAIN | If suported by underlying audio, this parameter allows you to set current gain setting. Refer to the SMLIMITS.H file for bounds on intput and output values. The IBM VoiceType Dictation adapter does not support the value, SM_AUDIO_INPUT_LINE_RIGHT.
  SM_CONNECTION_ID |
  SM_ENABLE_EXCLUSIVE_VOCABS | Sets the calling application's vocabularies.
  SM_ENGINE_DEBUG | Reserved. Values that can be set include the following: 0 is disabled, greater than 0 provides progressively more information.
  SM_ENGINE_DISPLAY | Reserved. Values that can be set include the following: 0 is disabled, greater than 0 provides progressively more information.
  SM_PM_ENABLE |
  SM_REJECTION_THRESHOLD | The speech engine rejects out-of-vocabulary words or background noise during monitored enrollment or command recognition. However, there is a trade-off between correctly rejecting these words/noises, and incorrectly rejecting properly spoken words. SM_REJECTION_THRESHOLD allows an application to adjust this trade-off. The limits for the value of this parameter are SM_MIN_REJECTION_THRESHOLD and SM_MAX_REJECTION_THRESHOLD, which are defined in SMLIMITS.H. At low settings of SM_REJECTION_THRESHOLD, the engine allows more matches through with fewer rejections. This causes more background noises or incorrect word matches to be recognized as speech. Fewer correct words are rejected. At high rejection threshold values, the engine is biased toward requiring a closer match, resulting in more rejections, and potentially more rejections of correct words. This parameter also determines how close the match must be between spoken acoustics and pronunciations in the SmAddPronunciation and SmWordCorrection calls. See SMLIMITS.H for minimum and maximum limits.
  SM_ENGINE_LOG | Reserved. Values that can be set include the following: 0 is disabled, greater than 0 provides progressively more information.
  SM_NOTIFY_AUDIO_LEVEL | Sets the returning of audio-level data during recognition or enrollment. The value is either TRUE (1) or FALSE (0). See SmGetAudioLevel for more information.
  SM_NOTIFY_COMMAND_WORD | Sets whether the application is notified when a command word is recognized by having the engine send a SM_COMMAND_WORD reply message. The value is either TRUE (1) or FALSE (0).
  SM_NOTIFY_ENGINE_STATE | Sets whether the application is notified of a speech engine state change. The value is either TRUE (1) or FALSE (0). See SmGetEngineState for more information.
  SM_NOTIFY_FOCUS_STATE | Sets whether the application is notified of a speech focus state change. The value is either TRUE (1) or FALSE (0). See SmGetFocusState for more information.
  SM_NOTIFY_MIC_STATE | Sets whether the application is notified of a microphone state change. The value is either TRUE (1) or FALSE (0). See SmGetMicState for more information.
  SM_REDUCED_CPU_MODE | Sets the CPU mode of the speech engine. The value is either TRUE (1) for reduced CPU mode, or FALSE (0) for normal CPU mode. See SmGetEngineState for more information.
  SM_SAVE_AUDIO | Enables or disables the saving of recorded audio during recognition. The value is either TRUE (1) or FALSE (0). For a monitored enrollment session, the default is TRUE, and for a recognition session, the default is FALSE.
  SM_ENGINE_TIMING - Reserved | Values that can be set include the following: 0 is disabled, greater than 0 provides progressively more information.

value

  input - The value to set the parameter to.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_BAD_MODE
    SM_RC_BAD_VALUE
    SM_RC_NOT_YET
    SM_RC_SERVER_FILE_OPEN_ERROR
    SM_RC_SERVER_ERROR

    SM_RC_EXISTS_IN_NOTIFY
    SM_RC_NOT_IN_NOTIFY

    For synchronous call and callbacks:
    SM_RC_NOT_VALID_REQUEST

Reply Structure Functions by Message Type

SM_SET_REPLY

- SmGetRc
- SmGetItemValue

For SM_NOTIFY_MIC_STATE parameter equal TRUE:
SM_MIC_STATE

- SmGetMicState
- SmGetRc

For SM_NOTIFY_FOCUS_STATE parameter equal TRUE:
SM_FOCUS_STATE

- SmGetApplication
- SmGetFocusState
- SmGetRc

For SM_NOTIFY_ENGINE_STATE parameter equal TRUE:
SM_ENGINE_STATE

- SmGetEngineState
- SmGetRc

For SM_NOTIFY_COMMAND_WORD parameter equal TRUE:
SM_COMMAND_WORD

- SmGetApplication
- SmGetFirmWords
- SmGetRc

For SM_NOTIFY_AUDIO_LEVEL parameter equal TRUE:
SM_AUDIO_LEVEL

- SmGetAudioLevel
- SmGetRc

Task Related Functions and Callbacks

    SmHaltRecognizer
    SmMicOff
    SmMicOn
    SmQuery
    SmRecognizeNextWord
    SmNhaltRecognizerCallback
    SmNmicOffCallback
    SmNmicOnCallback
    SmNqueryCallback
    SmNrecognizeNextWordCallback
    SmNrecognizedTextCallback
    SmNrecognizedWordCallback
    SmNsetCallback
    SmNutteranceCompletedCallback

## SmSetArg

Purpose

SmSetArg is a macro that fills an SmArg structure when given its components.

This function sets the components of the arg parameter. The pointer to arg or to a list of similarly created arguments can then be passed to a number of functions, such as SmOpen, and SmConnect.

For further information on attributes, see "SMAPI Attributes".

Syntax

    void SmSetArg (SmArg  arg,
                   char  *name,
                   long   value);

Parameters

arg

  input - The argument.

name

  input - The name of the attribute.

value

  input - The value of the attribute.

Return Values None

Task Related Functions and Callbacks

    SmConnect
    SmOpen
    SmNconnectCallback

## SmSetDefault

Purpose

SmSetDefault sets a default value for a user, enrollment, or task ID speech attribute. This default value is used by the speech engine when SM_USE_DEFAULT is specified for the speech attribute or when the speech attribute is specified. These attributes can be specified with SmOpen and SmConnect.

Syntax

    int SmSetDefault (long    item,
                      char   *item_value,
                      SM_MSG *reply);

Parameters

item

  input - Type of default ID speech attribute. Valid values include the following:
  - SM_DEFAULT_USERID
  - SM_DEFAULT_ENROLLID
  - SM_DEFAULT_TASK

item_value

  input - Value for default ID speech attribute.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_OK

Reply Structure Functions by Message Type

SM_SET_DEFAULT_REPLY

- SmGetRc

Task Related Functions and Callbacks

    SmConnect
    SmOpen
    SmQueryDefault

## SmSetUserInfo

Purpose

SmSetUserInfo sets user information.

This function stores any information that pertains to a user ID or an enrollment ID. It is the responsibility of the speech-aware application to select a proper item name (tag) that uniquely identifies stored information. This item is used later by the SmQueryUserInfo function for retrieving the stored information. This function allows an application to associate string information with a particular user ID or enrollment ID.

Syntax

    int SmSetUserInfo (char   *user_id,
                       char   *enroll_id,
                       char   *itemname,
                       char   *itemvalue,
                       SM_MSG *reply);

Parameters

user_id

  input - The name of the user whose information is stored.

enroll_id

  input - The enrollment ID of the user whose information is to be stored. This parameter is NULL if the information stored is related to the user ID.

itemname

  input - The name of the information item to be stored.

itemvalue

  input - The value of the information item to be stored.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_INVALID_PARM_MAX_LEN

    For synchronous call and callbacks:
    SM_RC_BAD_ENROLLID
    SM_RC_BAD_ITEM
    SM_RC_BAD_USERID

Reply Structure Functions by Message Type

SM_SET_USER_INFO_REPLY

- SmGetEnrollId
- SmGetEnrollIds
- SmGetRc
- SmGetUserId
- SmGetUserIds

Task Related Functions and Callbacks

    SmQueryUserInfo
    SmQueryUsers
    SmNqueryUsersCallback
    SmNqueryUserInfoCallback
    SmNsetUserInfoCallback

## SmUndefineVocab

Purpose

SmUndefineVocab deletes a dynamic vocabulary.

This function deletes a vocabulary defined by a SmDefineVocab call. After the vocabulary is deleted, no calls to SmEnableVocab, SmDisableVocab, SmAddToVocab, or SmRemoveFromVocab can be made for the specified vocabulary. The specified vocabulary must be disabled to be deleted.

SmUndefineVocab release the image of the private area of the FSG file.

SmUndefineVocab is valid only when the speech engine is not decoding speech to text.

Syntax

    int SmUndefineVocab (char   *vocab,
                         SM_MSG *reply);

Parameters

vocab

  input - The name of the vocabulary undefined.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

Return Values

    SM_RC_BAD_VOCAB
    SM_RC_DEALLOCATING_SH_MEM
    SM_RC_EALLOC
    SM_RC_EBADHANDLE
    SM_RC_ENOCONN
    SM_RC_ENOMEM
    SM_RC_ENOMSG
    SM_RC_ENOSERVER
    SM_RC_EUNEXP
    SM_RC_SM_NOT_OPEN
    SM_RC_OK
    SM_RC_INVALID_PARM_MAX_LEN

    For synchronous call and callbacks:
    SM_RC_NOT_VALID_REQUEST

Reply Structure Functions by Message Type

SM_UNDEFINE_VOCAB_REPLY

- SmGetRc
- SmGetVocabName

Task Related Functions and Callbacks

    SmAddToVocab
    SmDefineVocab
    SmDisableVocab
    SmEnableVocab
    SmGetAnnotations
    SmQueryAddedWords
    SmQueryEnabledVocabs
    SmQueryVocabs
    SmQueryWord
    SmRemoveFromVocab
    SmNaddToVocabCallback
    SmNdefineVocabCallback
    SmNdisableVocabCallback
    SmNenableVocabCallback
    SmNqueryAddedWordsCallback
    SmNqueryEnabledVocabsCallback
    SmNqueryVocabsCallback
    SmNqueryWordsCallback
    SmNremoveFromVocabCallback
    SmNundefineVocabCallback

## SmWordCorrection

Purpose

SmWordCorrection corrects a misrecognized word.

This function notifies the speech engine that an incorrectly recognized word or sequence of words was corrected by the user.

The user corrects the word by providing the correct spelling. This call specifies whether the pronunciation for this word is to be added to the user's personal pronunciation pool and whether the corrected spelling is to be added to the user's personal text vocabulary extension. The speech engine uses this information to assist future recognition.

If an SmWordCorrection call fails and the call is immediately repeated with exactly the same parameters, the engine will automatically apply more lenient threshold parameters the second time (refer to SmSet for a detailed description of the SM_REJECTION_THRESHOLD parameter).

This call is valid only when the speech engine is not decoding speech to text.

Note: For this call to be valid, the application must first enable audio saving through SmSet(SM_SAVE_AUDIO, TRUE).

Syntax

    int SmWordCorrection (short   ntags,
                          long    tags[],
                          short   nspells,
                          char   *spellings[],
                          char   *pronunciations[],
                          short   new_pronunciation,
                          SM_MSG *reply);

Parameters

ntags

  input - The number of tagged words corrected.

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 engine produces a pronunciation if one does not already exist.
  SM_REPLACE_ADDWORD | The new pronunciation needs to replace any existing pronunciations of the corrected word.

reply

  input/output - The pointer to a reply structure or to SmAsynchronous indicating that the call is made asynchronously.

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_MULTIPLE_SPELLINGS
    SM_RC_NOT_VALID_REQUEST

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
    SmNplayWordsStatusCallback
    SmNqueryAddedWordsCallback
    SmNqueryWordsCallback
    SmNremovePronunciationCallback
    SmNwordCorrectionCallback
    SmPlayWords
    SmQueryAddedWords
    SmQueryWord
    SmRemovePronunciation

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