# Application Programming Interface (API) Reference

# Data Access Functions

This chapter lists and describes the function calls that retrieve data from reply messages. These function calls do not interact with the engine; they provide local access to the logical contents of a message that has already been received.

## SmGetAlphabets

Purpose

SmGetAlphabets retrieves a list of alphabets related to specific enroll IDs or tasks.

SmGetAlphabets retrieves a list of alphabet strings. This function can extract data from the following reply message structures:

- SM_QUERY_ENROLLIDS_REPLY
- SM_QUERY_TASKS_REPLY

The alphabet identifies the base technology used in the engine. Enrollment data must match engine technology. The current engine is using a ranks based technology (alphabet="R".). The previous engine used a Z-label based technology (alphabet="Z".).

Syntax

    int SmGetAlphabets  (SM_MSG           reply,
                         unsigned long   *nalphabets,
                         char          ***alphabets);

Parameters

reply

  input - The reply structure from a SMAPI function.

nalphabets

  output - The pointer to the number of alphabets.

alphabets

  output - The pointer to a list of alphabets.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryEnrollIds
    SmQueryTasks

## SmGetAlternates

Purpose

SmGetAlternates retrieves alternative words.

SmGetAlternates retrieves the list of alternative words from the reply message. This function can extract data from the following reply message structures:

- SM_QUERY_ALTERNATES_REPLY
- SM_RECOGNIZED_WORD

Syntax

    int SmGetAlternates (SM_MSG          reply,
                         unsigned long  *nwords,
                         SM_WORD       **words);

Parameters

reply

  input - The reply structure from a SMAPI function.

nwords

  output - The pointer to the number of alternative words.

words

  output - The pointer to a list of alternative words.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryAlternates

## SmGetAnnotations

Purpose

SmGetAnnotations retrieves annotations.

SmGetAnnotations extracts the base vocabulary name from the reply message, uses this name to access the image of the private area of the FSG file, and uses the offsets stored in SM_WORD to access the annotation data. This function can extract data from the following reply message structures:

- SM_RECOGNIZED_PHRASE

Annotations are stored in an SM_ANNOTATION structure. SmGetAnnotations returns a pointer to this structure. SM_ANNOTATION is defined as :

    struct _SM_ANNOTATION (
      long      type;            // Type of annotation
      union
      {
          long  numeric;         // Return numeric annotations
          char  *string;         // Return string annotations
          void  *other;          // Reserved
      }  annodata;
    );

Types of annotations are defined as :

- SM_ANNOTATION_NONE

- SM_ANNOTATION_NUMERIC

- SM_ANNOTATION_STRING

- SM_ANNOTATION_OTHER (Reserved)

The SM_ANNOTATION structure has a one-to-one correspondence with the corresponding SM_WORD structure. Lack of an annotation on a particular word is indicated by an annotation of type SM_ANNOTATION_NONE.

Syntax

    int SmGetAnnotations (SM_MSG         reply,
                         unsigned long  *nwords,
                         SM_ANNOTATION **annotations);

Parameters

reply

  input - The reply structure from a SMAPI function.

nwords

  output - The pointer to the number of annotations.

annotations

  output - The pointer to an annotation structure.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_SERVER_FILE_READ_ERROR

Reply Structure - Related Functions and Callbacks

    SmDefineGrammar
    SmUndefineVocab

## SmGetApplication

Purpose

SmGetApplication retrieves the name of the application.

SmGetApplication extracts the application name from the following reply messages:

- SM_COMMAND_WORD
- SM_FOCUS_STATE

Syntax

    int SmGetApplication (SM_MSG   reply,
                          char   **application);

Parameters

reply

  input - The reply structure from a SMAPI function.

application

  output - The pointer to the name of the application.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmNcommandWordCallback
    SmNfocusStateCallback

## SmGetApplications

Purpose

SmGetApplications retrieves the names of the applications that have established a session.

SmGetApplications extracts the application names from the SM_QUERY_SESSIONS_REPLY reply message sent by the speech engine to the application.

Syntax

    int SmGetApplications (SM_MSG         reply,
                           unsigned long  *nsessions
                           char           ***reco_sessions);

Parameters

reply

  input - The reply structure from a SMAPI function.

nsessions

  output - A pointer to the number of sessions that have been established with the speech engine.

reco_sessions

  output - A pointer to a list of applications that have established sessions with the speech engine.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmNquerySessionsCallback

## SmGetAudioLevel

Purpose

SmGetAudioLevel retrieves the level of the audio signal during recognition.

SmGetAudioLevel provides information about the level of audio received by the speech engine when the microphone is on. If previously requested by the SM_AUDIO_INPUT_LEVEL parameter supplied to the SmSet function, packets of audio level values are periodically sent to the speech engine, which in turn calls SmNaudioLevelCallback and/or sends a message to your window procedure. Audio-level information can then be obtained using this function. Audio-level values range from 0(SM_MIN_AUDIO_LEVEL) to 10(SM_MAX_AUDIO_LEVEL) with acceptable volume ranges from 2 to 7. The average rate sent by the engine is 5 audio-level values per second. This function can extract data from the following reply message structures:

- SM_AUDIO_LEVEL

Syntax

    int SmGetAudioLevel (SM_MSG       reply,
                         short       *volume);

Parameters

reply

  input - The reply structure from a SMAPI function.

volume

  output - The pointer to a short. Volume can range from SM_MIN_AUDIO_LEVEL to SM_MAX_AUDIO_LEVEL inclusive.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmNaudioLevelCallback

## SmGetDescriptions

Purpose

SmGetDescriptions retrieves a list of enrollment enroll IDs, scripts, tasks, or users.

SmGetDescriptions can extract data from the following reply message structures:

- SM_QUERY_ENROLLIDS_REPLY
- SM_QUERY_SCRIPTS_REPLY
- SM_QUERY_TASKS_REPLY
- SM_QUERY_USERS_REPLY

Syntax

    int SmGetDescriptions (SM_MSG           reply,
                           unsigned long   *ndescriptions,
                           char          ***descriptions);

Parameters

reply

  input - The reply structure from a SMAPI function.

ndescriptions

  output - The pointer to the number of descriptions.

descriptions

  output - The pointer to a list of descriptions.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryEnrollIds
    SmQueryLanguages
    SmQueryTasks
    SmQueryUsers

## SmGetEngineState

Purpose

SmGetEngineState retrieves the engine state.

SmGetEngineState extracts the engine state from an SM_GET_ENGINE_STATE reply message sent by the speech engine to an application. SM_GET_ENGINE_STATE reply messages are controlled by the SM_NOTIFY_ENGINE_STATE parameter of the SmSet function.

Syntax

    int SmGetEngineState (SM_MSG           reply,
                          unsigned long   *engine_state);

Parameters

reply

  input - The reply structure from a SMAPI function.

engine_state

  output - The pointer to an unsigned long. Values include the following:
  - SM_NOTIFY_NORMAL_CPU
  - SM_NOTIFY_REDUCED_CPU
  - SM_NOTIFY_ENGINE_BUSY
  - SM_NOTIFY_ENGINE_IDLE
  - SM_NOTIFY_NAVIGATOR_EXCLUSIVE
  - SM_NOTIFY_FOCUS_APP_EXCLUSIVE
  - SM_NOTIFY_NONE_EXCLUSIVE
  - SM_NOTIFY_RECOGNIZED_SPEECH
  - SM_NOTIFY_SPEECH_START
  - SM_NOTIFY_SPEECH_STOP
  - SM_NOTIFY_PRONUNCIATIONS_ADDED
  - SM_NOTIFY_PRONUNCIATIONS_DELETED
  - SM_NOTIFY_ENGINE_SETTINGS_CHANGED
    for the following parameters:
    - SM_REJECTION_THRESHOLD
    - SM_AUDIO_CONFIGURATION
    - SM_AUDIO_DEVICE
    - SM_AUDIO_INPUT_GAIN
    - SM_AUDIO_INPUT_MODE
    - SM_AUDIO_OUTPUT_GAIN
    - SM_AUDIO_OUTPUT_MODE
  - SM_NOTIFY_APPLICATION_CONNECTED
  - SM_NOTIFY_APPLICATION_DISCONNECTED

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmNengineStateCallback

## SmGetEnrollId

Purpose

SmGetEnrollId retrieves an enrollment ID.

SmGetEnrollId is valid only for reply message structures that contain one enrollment ID. Use SmGetEnrollIds for reply message structures with multiple enrollment IDs. SmGetEnrollId can extract data from the following reply message structures:

- SM_CONNECT_REPLY
- SM_QUERY_DEFAULT_REPLY
- SM_QUERY_USER_INFO_REPLY
- SM_SET_USER_INFO_REPLY

Syntax

    int SmGetEnrollId (SM_MSG           reply,
                       char           **enroll_id);

Parameters

reply

  input - The reply structure from a SMAPI function.

enroll_id

  output - The pointer to an enrollment ID.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryDefault
    SmQueryEnrollIds
    SmQueryUserInfo
    SmSetUserInfo

## SmGetEnrollIds

Purpose

SmGetEnrollIds retrieves a list of enrollment IDs.

This function can extract data from the following reply message structures:

- SM_QUERY_DEFAULT_REPLY
- SM_QUERY_SESSIONS_REPLY
- SM_CONNECT_REPLY
- SM_QUERY_ENROLLIDS_REPLY
- SM_QUERY_USER_INFO_REPLY
- SM_SET_USER_INFO_REPLY

Syntax

    int SmGetEnrollIds (SM_MSG           reply,
                        unsigned long   *nenroll_ids,
                        char          ***enroll_ids);

Parameters

reply

  input - The reply structure from a SMAPI function.

nenroll_ids

  output - The pointer to the number of enrollment IDs.

enroll_ids

  output - The pointer to a list of enrollment IDs.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryEnrollIds
    SmQueryUserInfo
    SmSetUserInfo

## SmGetEventId

Purpose

SmGetEventId retrieves the event ID.

SmGetEventId can extract data from the following reply message structures:

- SM_EVENT_NOTIFY_REPLY
- SM_EVENT_SYNCH

Syntax

    int SmGetEventId (SM_MSG         reply,
                      unsigned long *event_id);

Parameters

reply

  input - The reply structure from a SMAPI function.

event_id

  output - The pointer to the event ID.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmEventNotify
    SmNeventSynchCallback

## SmGetEventOptions

Purpose

SmGetEventOptions retrieves options for an event.

SmGetEventOptions can extract data from the following reply message structure:

- SM_EVENT_SYNCH

Syntax

    int SmGetEventOptions (SM_MSG         reply,
                           unsigned long *options);

Parameters

reply

  input - The reply structure from a SMAPI function.

options

  output - The pointer to options.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmNeventSynchCallback

## SmGetFirmWords

Purpose

SmGetFirmWords retrieves firm words.

SmGetFirmWords extracts the SM_WORD from the following reply message structures:

- SM_RECOGNIZED_PHRASE
- SM_RECOGNIZED_TEXT
- SM_RECOGNIZED_WORD

Syntax

    int SmGetFirmWords (SM_MSG          reply,
                        unsigned long  *nwords,
                        SM_WORD       **words);

Parameters

reply

  input - The reply structure from a SMAPI function.

nwords

  output - The pointer to the number of firm words.

words

  output - The pointer to a list of firm words.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmNrecognizedTextCallback
    SmNrecognizedWordCallback
    SmNcommandWordCallback

## SmGetFocusState

Purpose

SmGetFocusState retrieves the focus state.

SmGetFocusState extracts the focus state from the SM_FOCUS_STATE reply message sent by the speech engine to an application. SM_FOCUS_STATE reply messages are controlled by the SmSet SM_NOTIFY_FOCUS_STATE parameter. The name of the application causing the focus change can be extracted from SM_FOCUS_STATE with SmGetApplication.

Syntax

    int SmGetFocusState (SM_MSG          reply,
                        unsigned long  *focus_state);

Parameters

reply

  input - The reply structure from an API function.

focus_state

  output - The pointer to an unsigned long. Values include the following:
  - SM_NOTIFY_FOCUS_REQUESTED
  - SM_NOTIFY_FOCUS_GRANTED
  - SM_NOTIFY_FOCUS_DENIED
  - SM_NOTIFY_FOCUS_RELEASED

Return Values None.

Reply Structure - Related Functions and Callbacks

    SmNfocusStateCallback

## SmGetGrammarPath

Purpose

SmGetGrammarPath retrieves the full path name of an FSG file.

SmGetGrammarPath extracts data from the following reply message structure:

- SM_DEFINE_GRAMMAR_REPLY

Syntax

    int SmGetGrammarPath (SM_MSG          reply,
                          char          **grammar_path);

Parameters

reply

  input - The reply structure from a SMAPI function.

grammar_path

  output - The pointer to the full path name.

Return Values

    SM_RC_OK
    SM_RC_REPLY_NULL
    SM_RC_EINVAL_MSG_TYPE

Reply Structure - Related Functions and Callbacks

    SmDefineGrammar

## SmGetInfirmWords

Purpose

SmGetInfirmWords retrieves infirm words.

SmGetInfirmWords can extract data from the following reply message structure:

- SM_RECOGNIZED_TEXT

Syntax

    int SmGetInfirmWords (SM_MSG          reply,
                          unsigned long  *nwords,
                          SM_WORD       **words);

Parameters

reply

  input - The reply structure from a SMAPI function.

nwords

  output - The pointer to the number of infirm words.

words

  output - The pointer to a list of infirm words.

Return Values

    SM_RC_OK
    SM_RC_REPLY_NULL
    SM_RC_EINVAL_MSG_TYPE

Reply Structure - Related Functions and Callbacks

    SmNrecognizedTextCallback

## SmGetItemValue

Purpose

SmGetItemValue retrieves the value for an item.

SmGetItemValue can extract data from the following reply message structures:

- SM_QUERY_REPLY
- SM_SET_REPLY

Syntax

    int SmGetItemValue (SM_MSG         reply,
                        unsigned long *item,
                        unsigned long *value);

Parameters

reply

  input - The reply structure from a SMAPI function.

item

  output - The pointer to the name of the item.

value

  output - The pointer to the value of the item.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQuery
    SmSet

## SmGetLanguages

Purpose

SmGetLanguages retrieves a list of languages.

SmGetLanguages can extract data from the following reply message structures:

- SM_CONNECT_REPLY
- SM_QUERY_ENROLLIDS_REPLY
- SM_QUERY_LANGUAGES_REPLY
- SM_QUERY_TASKS_REPLY

Syntax

    int SmGetLanguages (SM_MSG           reply,
                        unsigned long   *nlanguages,
                        char          ***languages);

Parameters

reply

  input - The reply structure from a SMAPI function.

nlanguages

  output - The pointer to the number of languages.

languages

  output - The pointer to a list of languages.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryEnrollIds
    SmQueryLanguages
    SmQueryTasks
    SmConnect

## SmGetMicState

Purpose

SmGetMicState gets the microphone state.

SmGetMicState extracts the microphone state from one of the following messages sent by the speech engine to the application:

- SM_REPORT_ENGINE_ERROR
- SM_FOCUS_GRANTED
- SM_MIC_STATE

SM_REPORT_ENGINE_ERROR is unsolicited, and SM_FOCUS_GRANTED and SM_MIC_STATE are sent if the application issues SmSet for SM_NOTIFY_FOCUS_STATE and SM_NOTIFY_MIC_STATE, respectively.

Syntax

    int SmGetMicState (SM_MSG         reply,
                       unsigned long *mic_state)

Parameters

reply

  input - The reply structure from a SMAPI function.

mic_state

  output - Pointer to an unsigned long, which can be any of the following:

  SM_REPORT_ENGINE_ERROR | SM_ENGINE_MIC_ON SM_ENGINE_MIC_OFF
  SM_FOCUS_GRANTED | SM_NOTIFY_MIC_ON SM_ENGINE_MIC_OFF SM_NOTIFY_MIC_PAUSED
  SM_MIC_STATE | SM_NOTIFY_MIC_ON SM_ENGINE_MIC_OFF SM_NOTIFY_MIC_PAUSED

Return Values None.

Reply Structure - Related Functions and Callbacks

    SmNmicStateCallback

## SmGetMsgName

Purpose

SmGetMsgName retrieves the name of the audio message.

SmGetMsgName can extract data from the following reply message structures:

- SM_PLAY_MESSAGE_STATUS

Syntax

    int SmGetMsgName (SM_MSG   reply,
                      char   **message_name);

Parameters

reply

  input - The reply structure from a SMAPI function.

message_name

  output - The pointer to the name of the audio message.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmNplayMessageStatusCallback

## SmGetMsgType

Purpose

SmGetMsgType retrieves the type of message from the reply structure associated with the input.

SmGetMsgType can extract data from the following reply message structures:

- SM_CONNECT_REPLY
- SM_DISCONNECT_REPLY

Syntax

    int SmGetMsgType (SM_MSG   reply,
                      int     *message_type);

Parameters

reply

  input - The reply structure from a SMAPI function.

message_type

  output - The message type.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

## SmGetNameValue

Purpose

SmGetNameValue retrieves a name and its value.

SmGetNameValue retrieves a name (tag) of user information and its corresponding value. This function can extract data from the following reply message structures:

- SM_QUERY_USER_INFO_REPLY

Syntax

    int SmGetNameValue (SM_MSG   reply,
                        char   **name,
                        char   **value);

Parameters

reply

  input - The reply structure from a SMAPI function.

name

  output - The pointer to the name.

value

  output - The pointer to the value of the name.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryUserInfo

## SmGetNumberWordMsgs

Purpose

SmGetNumberWordMsgs gets the number of words from a message.

SmGetNumberWordMsgs retrieves the number of SM_RECOGNIZED_WORD messages that have been sent since the last SM_RECOGNIZE_NEXT_WORD function call request. The value returned is 0 or 1. This is used with a synchronous SM_HALT_RECOGNIZER_REPLY message to tell if any unprocessed command words are still queued.

Syntax

    int SmGetNumberWordMsgs (SM_MSG        *reply,
                             unsigned long *nwords )

Parameters

reply

  input - The reply structure from a SMAPI function.

nwords

  output - Pointer to an unsigned long that will be filled in with the number of words.

Return Values

    SM_RC_SM_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

## SmGetPercentages

Purpose

SmGetPercentages retrieves percentages of the completeness of processing for specified enrollments.

SmGetPercentages can extract data from the following reply message structure:

- SM_QUERY_ENROLLIDS_REPLY

A query of enrollids for a given user returns an array of enrollids, with related fields, such as language or percent complete. This procedure provides an array of the percent-complete values.

Syntax

    int SmGetPercentages (SM_MSG          reply,
                          unsigned long  *npercentages,
                          short         **percentages);

Parameters

reply

  input - The reply structure from a SMAPI function.

npercentages

  output - The pointer to the number of percentages.

percentages

  output - The pointer to a list of percentages.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryEnrollIds

## SmGetPhraseState

Purpose

SmGetPhraseState retrieves phrase state flags.

SmGetPhraseState can extract data from the following reply message structure:

- SM_RECOGNIZED_PHRASE

Syntax

    int SmGetPhraseState (SM_MSG              reply,
                          unsigned long      *phrase_state,

Parameters

reply

  input - The reply structure from a SMAPI function.

phrase_state

  output - The pointer to an usnigned long which can be any of the following:

  SM_PHRASE_ACCEPTED | The engine has accepted the phrase.
  SM_PHRASE_HALTED | The engine is in a halted state and is waiting for the application to tell it what to do next.
  SM_PHRASE_REJECTED | The engine has rejected the phrase, with the best guess phrase returned in the SM_WORD array.

Return Values

    SM_RC_OK
    SM_RC_REPLY_NULL
    SM_RC_EINVAL_MSG_TYPE

Reply Structure - Related Functions and Callbacks

    SmNRecognizedPhraseCallback

## SmGetPronunciations

Purpose

SmGetPronunciations retrieves pronunciations.

SmGetPronunciations can extract data from the following reply message structures:

- SM_QUERY_PRONUNCIATIONS_REPLY
- SM_WORD_CORRECTION_REPLY

Syntax

    int SmGetPronunciations (SM_MSG           reply,
                             unsigned long   *npronun,
                             char          ***pronuns);

Parameters

reply

  input - The reply structure from a SMAPI function.

npronun

  output - The pointer to the number of pronunciations.

pronuns

  output - The pointer to a list of pronunciations.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryPronunciations
    SmWordCorrection

## SmGetRc

Purpose

SmGetRc retrieves the return code for the SMAPI functions.

Syntax

    int SmGetRc (SM_MSG  reply,
                 int    *rc);

Parameters

reply

  input - The reply structure from a SMAPI function.

rc

  output - The pointer to the return code.

Return Values

    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    All functions.

## SmGetRcDescription

Purpose

SmGetRcDescription retrieves the ASCII string describing the return code.

SmGetRcDescription remaps return codes to ASCII strings that describe the return code and, potentially, the associated failure. Messages are in US English only for diagnostic purposes. This function returns a pointer to an ASCII character string that describes the return code in the parameter rc_description. For example, for the symbolic return code "SM_RC_ACOUSTICS_TOO_LONG", the associated return code description character string would be "The acoustics specified are too long." For a list of all return code character strings, see "SMAPI Message Explanations".

Syntax

    int SmGetRcDescription (SM_MSG     reply,
                            char     **rc_description);

Parameters

reply

  input - The reply structure from a SMAPI function.

rc_description

  output - Pointer to a character string.

Return Values

    SM_RC_OK
    SM_RC_REPLY_NULL

## SmGetRcName

Purpose

SmGetRcName returns the symbolic name of the return code as a string.

SmGetRcName retrieves the ASCII strings containing the symbol associated with the return code as a string. For example, for a return code value of 49, the associated symbolic return code name character string would be SM_RC_ACOUSTICS_TOO_LONG. For a list of all return code values, see "SMAPI Return Codes and Messages".

Syntax

    int SmGetRcName (SM_MSG      reply,
                     char      **rc_name);

Parameters

reply

  input - Any return code associated with any Sm call.

rc_name

  output - Pointer to a character string.

Return Values

    SM_RC_OK
    SM_RC_REPLY_NULL

## SmGetScripts

Purpose

SmGetScripts retrieves a list of enrollment scripts.

SmGetScripts can extract data from the following reply message structures:

- SM_QUERY_DEFAULT_REPLY
- SM_QUERY_ENROLLIDS_REPLY

Syntax

    int SmGetScripts (SM_MSG             reply,
                      unsigned long     *nscripts,
                      char            ***scripts);

Parameters

reply

  input - The reply structure from a SMAPI function.

nscripts

  output - The pointer to the number of scripts.

scripts

  output - The pointer to a list of scripts.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryEnrollIds

## SmGetService

Purpose

SmGetService retrieves a pointer to the argument name describing the service requested from the speech engine.

SmGetService can extract data from the following reply message structures:

- SM_CONNECT_REPLY
- SM_DISCONNECT_REPLY

Syntax

    int SmGetService (SM_MSG     reply,
                      char     **service);

Parameters

reply

  input - The reply structure from a SMAPI function.

service

  output - The pointer to the service name.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmConnect
    SmDisconnect

## SmGetSessionId

Purpose

SmGetSessionId retrieves the session ID from the reply structure.

SmGetSessionId can extract data from the following reply message structure:

- SM_CONNECT_REPLY

Syntax

    int SmGetSessionId (SM_MSG     reply,
                        char     **session_id);

Parameters

reply

  input - The reply structure from a SMAPI function.

session_id

  output - The pointer to the ID of the session.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmConnect

## SmGetSeverity

Purpose

SmGetSeverity retrieves the severity associated with an unsolicited SM_REPORT_ENGINE_ERROR message.

Syntax

    int SmGetSeverity (SM_MSG           reply,
                       unsigned long   *severity)

Parameters

reply

  input - The reply structure from a SMAPI function.

severity

  output - Pointer to an unsigned long that will be filled in with the severity. Values include the following:

  SM_ENGINE_INFO | Informational message/can be ignored.
  SM_ENGINE_WARNING | Non-terminal error detected by engine.
  SM_ENGINE_ERROR | Currently unused, but can be used in the future.
  SM_ENGINE_TERMINAL_ERROR | Engine terminated due to unrecoverable error.

Return Values

    SM_RC_SM_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

## SmGetSpeechDataArchive

Purpose

SmGetSpeechDataArchive retrieves the name of the archive file.

SmGetSpeechDataArchive extracts data associated with the following reply message structures:

- SM_SAVE_SPEECH_DATA_REPLY
- SM_RESTORE_SPEECH_DATA_REPLY

Syntax

    int SmGetSpeechDataArchive (SM_MSG     reply,
                                char     **archive);

Parameters

reply

  input - The reply structure from a SMAPI function.

archive

  output - The pointer to the archive name.

Return Values

    SM_RC_OK
    SM_RC_REPLY_NULL
    SM_RC_SM_EINVAL_MSG_TYPE

Reply Structure - Related Functions and Callbacks

    SmSaveSpeechData
    SmRestoreSpeechData

## SmGetSpeechDataOptions

Purpose

SmGetSpeechDataOptions retrieves the options flags.

SmGetSpeechDataOptions extracts data associated with the following reply message structure:

- SM_SAVE_SPEECH_DATA_REPLY

Syntax

    int SmGetSpeechDataOptions (SM_MSG     reply,
                                long      *options);

Parameters

reply

  input - The reply structure from a SMAPI function.

options

  output - The pointer to the options flags, which can be one of the following:

  SM_NORMAL_FILE | This indicates that the speech data was written to a flat file. It will contain only engine data.
  SM_COMPOUND_FILE | This indicates that the speech data is written to a file, and the data is saved in a section named "VTDSessionArchive." The file can contain both engine state and application state data.

Return Values

    SM_RC_OK
    SM_RC_REPLY_NULL
    SM_RC_SM_EINVAL_MSG_TYPE

Reply Structure - Related Functions and Callbacks

    SmSaveSpeechData

## SmGetSpeechDataSize

Purpose

SmGetSpeechDataSize retrieves the size of the speech data archive.

SmGetSpeechDataSize extracts data associated with the following reply message structures:

- SM_SAVE_SPEECH_DATA_REPLY
- SM_QUERY_SPEECH_DATA_REPLY

Syntax

    int SmGetSpeechDataSize (SM_MSG          reply,
                             unsigned long  *size);

Parameters

reply

  input - The reply structure from a SMAPI function.

size

  output - The pointer to the size of the speech data archive.

Return Values

    SM_RC_OK
    SM_RC_REPLY_NULL
    SM_RC_SM_EINVAL_MSG_TYPE

Reply Structure - Related Functions and Callbacks

    SmQuerySpeechData
    SmSaveSpeechData

## SmGetSpeechDataVersion

Purpose

SmGetSpeechDataVersion retrieves the version identifier.

SmGetSpeechDataVersion extracts data associated with the following reply message structures:

- SM_SAVE_SPEECH_DATA_REPLY
- SM_RESTORE_SPEECH_DATA_REPLY

Syntax

    int SmGetSpeechDataVersion (SM_MSG          reply,
                                long           *version);

Parameters

reply

  input - The reply structure from a SMAPI function.

version

  output - The pointer to the version identifier.

Return Values

    SM_RC_OK
    SM_RC_REPLY_NULL
    SM_RC_SM_EINVAL_MSG_TYPE

Reply Structure - Related Functions and Callbacks

    SmRestoreSpeechData
    SmSaveSpeechData

## SmGetSpelling

Purpose

SmGetSpelling gets the spelling from a message.

SmGetSpelling extracts data and retrieves the spelling associated with the following reply message structures:

- SM_ADD_PRONUNCIATION_REPLY
- SM_QUERY_PRONUNCIATION_REPLY
- SM_REMOVE_PRONUNCIATION_REPLY

Syntax

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

Parameters

reply

  input - The reply structure from a SMAPI function.

spelling

  output - Pointer to a character string.

Return Values

    SM_RC_SM_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmAddPronunciation
    SmQueryPronunciation
    SmRemovePronunciation
    SmWordCorrection

## SmGetSpellings

Purpose

SmGetSpellings retrieves spellings.

SmGetSpellings extracts data and retrieves the spelling associated with the following reply message structures:

- SM_ADD_PRONUNCIATION_REPLY
- SM_QUERY_PRONUNCIATIONS_REPLY
- SM_REMOVE_PRONUNCIATION_REPLY
- SM_WORD_CORRECTION_REPLY

Syntax

    int SmGetSpellings (SM_MSG             reply,
                        unsigned long     *nspellings,
                        char            ***spellings);

Parameters

reply

  input - The reply structure from a SMAPI function.

nspellings

  output - The pointer to the number of spellings.

spellings

  output - The pointer to a list of spellings.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmAddPronunciation
    SmQueryPronunciations
    SmRemovePronunciation
    SmWordCorrection

## SmGetStates

Purpose

SmGetStates retrieves enrollment statuses.

SmGetStates can extract data from the following reply message structure:

- SM_QUERY_ENROLLIDS_REPLY

Syntax

    int SmGetStates (SM_MSG            reply,
                    unsigned long     *nstati,
                    short            **stati);

Parameters

reply

  input - The reply structure from a SMAPI function.

nstati

  output - The pointer to the number of statuses.

stati

  output - The pointer to a list of statuses. Values include the following:
  - SM_STAT_ENROLLMENT_RECORDING
  - SM_STAT_ENROLLMENT_RUNNING
  - SM_STAT_ENROLLMENT_COMPLETE
  - SM_STAT_ENROLLMENT_FAILED
  - SM_STAT_ENROLLMENT_BUSY

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryEnrollIds

## SmGetStatus

Purpose

SmGetStatus retrieves the status.

SmGetStatus can extract data from the following reply message structures:

- SM_PLAY_MESSAGE_STATUS
- SM_PLAY_UTTERANCE_STATUS
- SM_PLAY_WORDS_STATUS
- SM_WORD_CORRECTION_REPLY

The SmGetStatus function retrieves the status from the reply structure. This status and its meaning depend on the related function that was called just before the SmGetStatus call. The following statuses are possible:

- For SmNplayMessageCallback, SmNplayUtteranceCallback, and SmNplayWordCallback:

  SM_STAT_PLAY_START | The message, utterance, or word playback started.
  SM_STAT_PLAY_STOP | The message, utterance, or word playback stopped.

- For SmNplayWordsStatusCallback:

  SM_STAT_BAD_AUDIO | The connection to the audio source was lost during playback.
  SM_STAT_BAD_TAG | An invalid tag value was specified for the word.

- For an SmWordCorrection call:

  SM_RC_ADDED | The word was added to the vocabulary.
  SM_RC_INVOCAB | The word is already in the vocabulary.
  SM_RC_NOT_INVOCAB | The word is not in the IBM VoiceType Dictation spelling dictionary.
  SM_RC_NOT_ADDED | The word has not been added to the vocabulary.

Syntax

    int SmGetStatus (SM_MSG  reply,
                     int    *status);

Parameters

reply

  input - The reply structure from a SMAPI function.

status

  output - The pointer to the status.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmWordCorrection
    SmNplayMessageStatusCallback
    SmNplayUtteranceStatusCallback
    SmNplayWordsStatusCallback

## SmGetTags

Purpose

SmGetTags retrieves tags from the reply structure.

SmGetTags can extract data from the following reply message structures:

- SM_PLAY_WORDS_STATUS
- SM_QUERY_ALTERNATES_REPLY
- SM_WORD_CORRECTION_REPLY

Syntax

    int SmGetTags (SM_MSG          reply,
                   unsigned long  *ntags,
                   long          **tags);

Parameters

reply

  input - The reply structure from a SMAPI function.

ntags

  output - The pointer to the number of tags.

tags

  output - The pointer to a list of tags.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryAlternates
    SmWordCorrection
    SmNplayWordsStatusCallback

## SmGetTask

Purpose

SmGetTask retrieves a domain from the reply structure.

SmGetTask is valid only for reply message structures that contain one domain. Use SmGetTasks for reply message structures with multiple domains. SmGetTask can extract data from the following reply message structures:

- SM_CONNECT_REPLY
- SM_QUERY_DEFAULT_REPLY
- SM_QUERY_TASKS_REPLY

Syntax

    int SmGetTask (SM_MSG           reply,
                   char           **domain);

Parameters

reply

  input - The reply structure from a SMAPI function.

domain

  output - The pointer to a domain.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryDefault
    SmQueryTasks

## SmGetTasks

Purpose

SmGetTasks retrieves domains from the reply structure.

This function can extract data from the following reply message structures:

- SM_CONNECT_REPLY
- SM_QUERY_DEFAULT_REPLY
- SM_QUERY_TASKS_REPLY

Syntax

    int SmGetTasks (SM_MSG           reply,
                    unsigned long   *ndomains,
                    char          ***domains);

Parameters

reply

  input - The reply structure from a SMAPI function.

ndomains

  output - The pointer to the number of domains.

domains

  output - The pointer to a list of domains.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryTasks

## SmGetTimes

Purpose

SmGetTimes retrieves time values of spoken words.

SmGetTimes retrieves an array of time values sent with words received in the last SM_RECOGNIZED_TEXT or SM_RECOGNIZED_WORD message from the speech engine. Each time, expressed in milliseconds, specifies the time elapsed from the beginning of the utterance to the beginning of the spoken word. This function can extract data from the following reply message structures:

- SM_RECOGNIZED_TEXT
- SM_RECOGNIZED_WORD

Syntax

    int SmGetTimes (SM_MSG          reply,
                    unsigned long  *ntimes,
                    unsigned long **times);

Parameters

reply

  input - The reply structure from a SMAPI function.

ntimes

  output - The pointer to the number of times in the list.

times

  output - The pointer to a list of times.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmNrecognizedTextCallback
    SmNrecognizedWordCallback
    SmNaudioEventCallback

## SmGetUserId

Purpose

SmGetUserId retrieves a user ID from the reply structure.

SmGetUserId is valid only for reply message structures that contain one user ID. Use SmGetUserIds for reply message structures with multiple user IDs. SmGetUserId can extract data from the following reply message structures:

- SM_CONNECT_REPLY
- SM_QUERY_DEFAULT_REPLY
- SM_QUERY_USER_INFO_REPLY
- SM_SET_USER_INFO_REPLY

Syntax

    int SmGetUserId (SM_MSG           reply,
                     char           **user_id);

Parameters

reply

  input - The reply structure from a SMAPI function.

user_id

  output - The pointer to a user ID.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryDefault
    SmQueryUserInfo
    SmQueryUsers
    SmSetUserInfo

## SmGetUserIds

Purpose

SmGetUserIds retrieves user IDs from the reply structure.

SmGetUserIds can extract data from the following reply message structures:

- SM_QUERY_DEFAULT_REPLY
- SM_QUERY_SESSIONS_REPLY
- SM_QUERY_USER_INFO_REPLY
- SM_QUERY_USERS_INFO_REPLY
- SM_QUERY_USERS_REPLY
- SM_SET_USER_INFO_REPLY

Syntax

    int SmGetUserIds (SM_MSG           reply,
                      unsigned long   *nuser_ids,
                      char          ***user_ids);

Parameters

reply

  input - The reply structure from a SMAPI function.

nuser_ids

  output - The pointer to the number of user IDs.

user_ids

  output - The pointer to a list of user IDs.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryUserInfo
    SmQueryUsers
    SmSetUserInfo

## SmGetUsers

Purpose

SmGetUsers retrieves users from the reply structure.

SmGetUsers can extract data from the following reply message structure:

- SM_QUERY_USERS_REPLY

Syntax

    int SmGetUsers (SM_MSG             reply,
                    unsigned long     *nusers,
                    char            ***users);

Parameters

reply

  input - The reply structure from a SMAPI function.

nusers

  output - The pointer to the number of users.

users

  output - The pointer to a list of users.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryUsers

## SmGetUtteranceNumber

Purpose

SmGetUtteranceNumber retrieves the utterance number from the reply structure.

SmGetUtteranceNumber can extract data from the following reply message structures:

- SM_MIC_ON_REPLY
- SM_PLAY_UTTERANCE_STATUS
- SM_UTTERANCE_COMPLETED

Syntax

    int SmGetUtteranceNumber (SM_MSG           reply,
                              unsigned long   *nutterance);

Parameters

reply

  input - The reply structure from a SMAPI function.

nutterance

  output - The pointer to the utterance number.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmMicOn
    SmNplayUtteranceStatusCallback
    SmNutteranceCompletedCallback

## SmGetVocabList

Purpose

The SmGetVocabList function retrieves a vocabulary list from the reply structure.

SmGetVocabList can extract data from the following reply message structures:

- SM_QUERY_ENABLED_VOCABS_REPLY
- SM_QUERY_VOCABS_REPLY
- SM_QUERY_WORD_REPLY

Syntax

    int SmGetVocabList (SM_MSG             reply,
                        unsigned long     *nvocabs,
                        char            ***vocabs);

Parameters

reply

  input - The reply structure from a SMAPI function.

nvocabs

  output - The pointer to the number of vocabularies in the vocabulary list.

vocabs

  output - The pointer to a list of vocabularies.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryEnabledVocabs
    SmQueryVocabs
    SmQueryWord

## SmGetVocabName

Purpose

SmGetVocabName retrieves the vocabulary name from the reply structure.

This function can extract data from the following reply message structures:

- SM_ADD_TO_VOCAB_REPLY
- SM_DEFINE_VOCAB_REPLY
- SM_DISABLE_VOCAB_REPLY
- SM_ENABLE_VOCAB_REPLY
- SM_REMOVE_FROM_VOCAB_REPLY
- SM_UNDEFINE_VOCAB_REPLY

Syntax

    int SmGetVocabName (SM_MSG      reply,
                        char      **vocabname);

Parameters

reply

  input - The reply structure from a SMAPI function.

vocabname

  output - The pointer to the name of the vocabulary.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmAddToVocab
    SmDefineVocab
    SmDisableVocab
    SmEnableVocab
    SmRemoveFromVocab
    SmUndefineVocab

## SmGetVocWords

Purpose

SmGetVocWords retrieves vocabulary words from the reply structure.

This function can extract data from the following reply message structures:

- SM_ADD_TO_VOCAB_REPLY
- SM_DEFINE_VOCAB_REPLY

Following an SmAddToVocab call, SmGetVocWords extracts the vocabulary words that failed to be added.

Following an SmDefineVocab call, SmGetVocWords extracts the vocabulary words that failed to be defined.

For a description of the SM_VOCWORD data type, see "Data Types".

Syntax

    int SmGetVocWords (SM_MSG            reply,
                       unsigned long    *nwords,
                       SM_VOCWORD      **words);

Parameters

reply

  input - The reply structure from a SMAPI function.

nwords

  output - The pointer to the number of vocabulary words.

words

  output - The pointer to a list of vocabulary words.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmAddToVocab
    SmDefineVocab

## SmGetWords

Purpose

SmGetWords retrieves words from the reply structure. SmGetWords can extract data from the following reply message structures:

- SM_QUERY_ADDED_WORDS_REPLY
- SM_QUERY_WORD_REPLY

Syntax

    int SmGetWords (SM_MSG            reply,
                    unsigned long    *nwords,
                    SM_WORD         **words);

Parameters

reply

  input - The reply structure from a SMAPI function.

nwords

  output - The pointer to the number of words.

words

  output - The pointer to a list of words.

Return Values

    SM_RC_EINVAL_MSG_TYPE
    SM_RC_OK
    SM_RC_REPLY_NULL

Reply Structure - Related Functions and Callbacks

    SmQueryAddedWords
    SmQueryWord

## SmReturnRc

Purpose

SmReturnRc returns the return code from SM_MSG.

SmReturnRc provides an alternative to SmGetRc for accessing return codes from messages received from the speech engine. The return value of the function is the return code value in the given SM_MSG.

Syntax

    int SmReturnRc (SM_MSG   reply);

Parameters

reply

  input - The reply structure from a SMAPI function.

Return Values

    SM_RC_OK
    SM_RC_REPLY_NULL

Task Related Functions and Callbacks

    SmReturnRcDescription
    SmReturnRcName

## SmReturnRcDescription

Purpose

SmReturnRcDescription retrieves the ASCII string describing the return code.

SmReturnRcDescription remaps return codes to ASCII strings that describe the return code and, potentially, the associated failure. Messages are in US English only for diagnostic purposes. For example, if this function were passed the return code, SM_RC_ACOUSTICS_TOO_LONG, a pointer to the associated return code description character string "The acoustics specified are too long." would be returned. For a list of all return code character strings, see "SMAPI Message Explanations".

Syntax

    char *SmReturnRcDescription (int  rc)

Parameters

rc

  input - Any return code associated with any Sm call.

Task Related Functions and Callbacks

    SmReturnRc
    SmReturnRcName

## SmReturnRcName

Purpose

SmReturnRcName returns the symbolic name of a return code as a string.

SmReturnRcName provides an alternative to SmGetRcName for retrieving an ASCII string containing the symbol associated with a return code. For example, if this function was passed the return code, SM_RC_ACOUSTICS_TOO_LONG, a pointer to the associated symbolic return code name character string "SM_RC_ACOUSTICS_TOO_LONG" would be returned. For a list of all return code values, see "SMAPI Return Codes and Messages".

Syntax

    char *SmReturnRcName (int  rc);

Parameters

rc

  input - Any return code associated with any Sm call.

Return Values

Function directly returns a pointer to a statically defined character string containing a description associated with the return code.

Refer to Appendix A. "SMAPI Return Codes and Messages" for a complete list of the character strings, their associated return values, and their symbolic return code names.

Task Related Functions and Callbacks

    SmReturnRc
    SmReturnRcDescription

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