Microsoft Speech SDK SAPI 5.1

---

ISpObjectToken::IsUISupported

ISpObjectToken::IsUISupported determines if the user interface (UI) associated with the object is supported.

Ultimately, ISpObjectToken::IsUISupported is similar to creating an ISpTokenUI object and calling ISpTokenUI::ISpIsUISupported.

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

Parameters

pszTypeOfUI

[in] Address of the null-terminated string containing the UI type that is being queried. Must be a SPDUI_xxx type.

pvExtraData

[in] Pointer to additional information needed for the object. The ISp TokenUI object implementer dictates the format and usage of the data provided. See Remarks section.

cbExtraData

[in] Size, in bytes, of the ExtraData. The ISpTokenUI object implementer dictates the format and usage of the data provided.

punkObject

[in] Address of the IUnknown interface pointer. See Remarks section.

pfSupported

[out] Address of a variable that receives the value indicating support for the interface. This value is set to TRUE when this interface is supported, and FALSE when it is not. If this 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

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

pvExtraData and punkObject Parameters: When asking an ISpObjectToken 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 QueryInterface off of a known IUnknown interface. The caller of ISpTokenUI::IsUISupported can set the punkObject parameter with the necessary IUnknown interface. For example, to display a Speech Recognition Training UI (see SPDUI_UserTraining) requires a specific SR engine.

Example

The following code snippet illustrates the use of ISpObjectToken::IsUISupported 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