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 ]

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

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