ISpTokenUI::DisplayUI

Article
06/30/2006

This method displays the UI associated with an object token. A call to this method is synchronous. Thus the method does not return until the UI has been closed.

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

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

Parameters

hwndParent
[in] Handle to the parent window.
pszTitle
[in] Pointer to a null-terminated string specifying the window title to display on the UI. This value can be set to NULL to indicate that the object implementing ISpTokenUI should use its default window title.
pszTypeOfUI
[in] Pointer to a null-terminated string specifying the type of UI to display.
pvExtraData
[in] Pointer to additional information needed for the object token. The implementation of ISpTokenUI dictates the format and use of the data provided.
cbExtraData
[in] Size, in bytes, of the data provided in pvExtraData.
pToken
[in] Pointer to an object implementing ISpObjectToken that represents the object token. See the Remarks section.
punkObject
[in] Pointer to IUnknown. See the Remarks section.

Return Values

The following table shows the possible return values.

Value	Description
S_OK	Function completed successfully.
S_FALSE	The UI is supported but not with the current run-time environment or parameters.
E_INVALIDARG	One or more arguments are invalid.
E_POINTER	Invalid or bad pointer.
FAILED(hr)	Error returned by UI object.

Remarks

When an object token is requested to display a particular piece of UI, the object implementing ISpObjectToken can require extra functionality that only it understands. For example, a request to display the speech recognition training UI requires the use of a specific SR engine.

Common implementation practice for accessing extra token functionality is to call QueryInterface for the object token, or directly create a known object implementing ISpObjectToken. If QueryInterface must be called, the caller of ISpTokenUI::DisplayUI can set punkObject with the necessary IUnknown interface. If the object token is known, the caller sets the pToken parameter with a pointer to the required ISpObjectToken interface.

Example

The following code snippet illustrates the use of this method using the UI type SPDUI_AudioVolume.

HRESULT hr = S_OK;
// get the default input audio object token
hr = SpGetDefaultTokenFromCategoryId(SPCAT_AUDIOIN, &cpObjectToken);
// Check hr

// get the object token's UI
hr = cpObjectToken->QueryInterface(&cpTokenUI);
// Check hr

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

// if fSupported == TRUE, then default 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: Sapiddk.h, Sapiddk.idl.
Link Library: Sapilib.lib.

Share via