ISpTokenUI::DisplayUI (SAPI 5.4)

Microsoft Speech API 5.4

ISpTokenUI::DisplayUI

ISpTokenUI::DisplayUI displays the UI associated with the object token.

  
    [local] HRESULT DisplayUI(
    HWND              hwndParent,
    const WCHAR      *pszTitle,
    const WCHAR      *pszTypeOfUI,
    void             *pvExtraData,
    ULONG             cbExtraData,
ISpObjectToken   *pToken,
IUnknown         *punkObject
);

Parameters

• hwndParent
  [in] Specifies the handle of the parent window.
• pszTitle
  [in] Address of a null-terminated string containing the window title to display on the UI. This value can be set to NULL to indicate that the TokenUI object should use its default window title.
• pszTypeOfUI
  [in] Address of a null-terminated string containing the UI type to display.
• pvExtraData
  [in] Pointer to additional information needed for the object. The ISp TokenUI object implementer dictates the format and usage of the data provided.
• cbExtraData
  [in] Size, in bytes, of the ExtraData. The ISp TokenUI object implementer dictates the format and usage of the data provided.
• pToken
  [in] Address of the ISpObjectToken containing the object token identifier. See Remarks section.
• punkObject
  [in] Address of the IUnknown interface pointer. See Remarks section.

Return values

Remarks

The best-practice for using ISpTokenUI is to call ISpTokenUI::IsUISupported with a specific UI type before calling DisplayUI.

The call to DisplayUI is synchronous, so the call will not return until the UI has been closed.

The token may require extra functionality that only it understands in order to display a particular piece of UI. Common implementation practice for accessing this functionality is to use QueryInterface of a known IUnknown interface or create the object associated a known ISpObjectToken instance. The caller of ISpTokenUI::DisplayUI can set punkObject with the necessary IUnknown interface or set pToken with the necessary ISpObjectToken interface. For example, asking to display Speech Recognition Training UI requires that a specific SR engine be used.

Example

The following code snippet illustrates the use of ISpTokenUI::DisplayUI using SPDUI_AudioVolume.

  
// Declare local identifiers:
HRESULT                      hr = S_OK;
CComPtr<ISpTokenUI>          cpTokenUI;
CComPtr<ISpObjectToken>      cpObjectToken;
BOOL                         fSupported;
const WCHAR                  *MY_AUDIO_DIALOG_TITLE = L"Foo Caption";
HWND                         hwndParent;

// Get the default input audio object token.
hr = SpGetDefaultTokenFromCategoryId(SPCAT_AUDIOIN, &cpObjectToken;);

if (SUCCEEDED(hr))
{
   // Get the object token's UI.
   hr = cpObjectToken->QueryInterface(&cpTokenUI;);
}

if (SUCCEEDED(hr))
{
   // Check if default audio input object has UI for volume.
   hr = cpTokenUI->IsUISupported(SPDUI_AudioVolume, NULL, NULL, NULL, &fSupported;);
}

if (SUCCEEDED(hr))
{
   // If fSupported == TRUE, then default audio input object has UI for Volume.

   // Display the default audio input object's Volume UI (you need
   // to have handle for hwndParent before executing next statement).
   hr = cpTokenUI->DisplayUI(hwndParent, MY_AUDIO_DIALOG_TITLE, SPDUI_AudioVolume, NULL, NULL, cpObjectToken, NULL);
}

if (SUCCEEDED(hr))
{
   // Do stuff here.
}