ISpRecognizer::GetInputObjectToken

This method gets the input token object for the stream currently being used. It always retrieves the default audio input object token when using a shared recognizer.

Applications will not typically need to use this method, but it can be used to find out specific details of the object token that was used to create the audio input stream.

If an application receives feedback from the SR engine that recognition quality is low, (for example, poor audio signal quality (see SPEI_INTERFERENCE), or that the microphone needs adjustment (see SPEI_REQUEST_UI for SPDUI_MicTraining), it may be helpful to reconfigure the audio input settings. SAPI defines two specific types of audio UI that an audio object token can provide: volume (SPDUI_AudioVolume) and properties (SPDUI_AudioProperties). An application can use GetInputObjectToken, ISpObjectToken::IsUISupported, and ISpObjectToken::DisplayUI to display audio UI in an effort to improve speech recognition.

HRESULT GetInputObjectToken(
  ISpObjectToken** ppToken
);

Parameters

  • ppToken
    [out] Address of a pointer to an object implementing ISpObjectToken for the stream currently being used.

Return Values

The following table shows the possible return values.

Value Description
S_OK Function completed successfully.
S_FALSE Function completed successfully, but the input stream object has no object token associated with it.
E_POINTER ppToken is invalid or bad.
SPERR_UNINITIALIZED No audio input has yet been set with SetInput (InProc engine only).
FAILED(hr) Appropriate error message.

Example

The following code snippet illustrates the use of this method when displaying audio UI.

HRESULT hr = S_OK;
// check if the current recognizer has an object token
hr = cpRecognizer->GetInputObjectToken(&cpObjectToken);
// Check hr == S_OK
// get the object token's UI
hr = cpObjectToken->QueryInterface(&cpTokenUI);
// Check hr
// check if the default audio input object has UI for Volume 
hr = cpTokenUI->IsUISupported(SPDUI_AudioVolume, NULL, NULL, NULL,
&fSupported);
// Check hr
// if fSupported == TRUE, then audio input object has UI for Volume
// Display the default audio input object's Volume UI 
hr = cpTokenUI->DisplayUI(MY_HWND, MY_AUDIO_DIALOG_TITLE, SPDUI_AudioVolume,
NULL, NULL, cpObjectToken, NULL);
// Check hr

Requirements

OS Versions: Windows CE .NET 4.1 and later.
Header: Sapi.h, Sapi.idl.
Link Library: Sapilib.lib.

See Also

ISpRecognizer | SAPI Interfaces

 Last updated on Saturday, April 10, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.