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.

    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