ISpObjectToken::IsUISupported

Article
06/30/2006

This method determines if the UI associated with the object is supported. Use of this method is similar to calling ISpTokenUI::IsUISupported.

[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 to query. Must be a SPDUI_xxx type.
pvExtraData
[in] Pointer to additional information needed for the object. The implementation of ISpTokenUI dictates the format and use of the data provided. See Remarks section.
cbExtraData
[in] Size, in bytes, of the extra data defined in pvExtraData.
punkObject
[in] Pointer to the IUnknown interface. See Remarks section.
pfSupported
[out] Pointer to a value indicating if the object token supports the UI. This value is TRUE when the UI is supported, and FALSE otherwise. If the value is TRUE, but the return code is S_FALSE, the UI type (guidTypeOfUI) is supported, but not with the current parameters or run-time environment. Check with the implementer 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 of the parameters is invalid or bad.
SPERR_UNINITIALIZED	Either the data key or token delegate interface is not initialized.
SPERR_TOKEN_DELETED	Key has been deleted.
FAILED(hr)	Appropriate error message.

Remarks

When the caller requests an ISpObjectToken implementation to display a particular piece of UI, the UI object may require extra functionality that only it understands. Common implementation practice for accessing this functionality is to call QueryInterface on a known IUnknown interface. The caller of ISpTokenUI::IsUISupported can set the punkObject parameter with the necessary IUnknown interface. For example, a request to display the Speech Recognition Training UI (see SPDUI_UserTraining) requires the use of a specific SR engine.

Example

The following code snippet illustrates the use of this method using SPGUID_EngineProperties.

    HRESULT hr = S_OK;

    // get the default text-to-speech engine object token
    hr = SpGetDefaultTokenFromCategoryId(SPCAT_VOICES, &cpObjectToken);
    // Check hr

    // create the engine object based on the object token
    hr = SpCreateObjectFromToken(cpObjectToken, &cpVoice);
    // Check hr

    // create a data key for the voice's UI objects
    hr = cpObjectToken->OpenKey(L"UI", &cpUIDataKey);
    // Check hr

    // create a data key for the specific Engine Properties UI
    hr = cpUIDataKey->OpenKey(SPDUI_EngineProperties, &cpEngPropsDataKey);
    // Check hr

    // get the GUID for the voice's engine properties UI
    hr = cpEngPropsDataKey->GetStringValue(L"CLSID", &pwszEngPropsCLSID);
    // Check hr

    // convert GUID string to pure GUID
    hr = CLSIDFromString(pwszEngPropsCLSID, &clsidEngProps);
    // Check hr

    // check if the default voice object has UI for Properties
    hr = cpObjectToken->IsUISupported(&clsidEngProps, NULL, NULL, cpVoice, &fSupported);
    // Check hr

    // if fSupported == TRUE, then default voice object has UI for Engine Properties

Requirements

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

Share via