ISpTokenUI::DisplayUI (Windows CE 5.0)
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.
See Also
Send Feedback on this topic to the authors