ISpTokenUI::IsUISupported

Article
06/30/2006

This method determines if the specified UI type is supported by an object token.

[local] HRESULT IsUISupported(
  const WCHAR* pszTypeOfUI,
  void* pvExtraData,
  ULONG cbExtraData,
  IUnknown* punkObject,
  BOOL* pfSupported
);

Parameters

pszTypeOfUI
[in] Pointer to a null-terminated string specifying the UI type.
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.
punkObject
[in] Pointer to IUnknown. See Remarks section.
pfSupported
[out] Pointer to a value indicating support for the UI. This value is set to TRUE if the requested UI type is supported, and to FALSE otherwise. If this value is TRUE, but the return code is S_FALSE, the UI type is supported, but not with the current parameters or run-time environment. The caller should check with the implementation of the UI object to verify run-time requirements.

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 SPDUI_AudioProperties.

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 the default audio input object has UI for Properties 
hr = cpTokenUI->IsUISupported(SPDUI_AudioProperties, NULL, NULL, NULL,
&fSupported);
// Check hr

// if fSupported == TRUE, then default audio input object has UI for Properties

Requirements

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

Share via