ISpObjectToken::IsUISupported

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

[local] HRESULT IsUISupported(
    LPCWSTR      *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. See Remarks section.

cbExtraData

[in] Size, in bytes, of the ExtraData.

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

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. For example, to display a Speech Recognition Training UI requires a specific SR engine.

Example

The following code snippet illustrates the use of ISpObjectToken::IsUISupported.

// Declare local identifiers:
HRESULT                    hr = S_OK;
CComPtr<ISpObjectToken>    cpObjectToken;
CComPtr<ISpVoice>          cpVoice;
BOOL                       fSupported;
HWND                       hwndParent;

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

if (SUCCEEDED(hr))
{
   // Create the engine object based on the object token.
   hr = SpCreateObjectFromToken(cpObjectToken, &cpVoice;);
}

if (SUCCEEDED(hr))
{
   // Check if the default engine object has UI for Properties.
   hr = cpObjectToken->IsUISupported(SPDUI_EngineProperties, NULL, NULL, cpVoice, &fSupported;);
}

if (SUCCEEDED(hr))
{
   // If default engine object has UI for
   // Engine Properties, display UI--
   if (fSupported == TRUE)
   {
      hr = cpObjectToken->DisplayUI(hwndParent, L"My App's Caption", SPDUI_EngineProperties, NULL, NULL, cpVoice);
   }
}

if (SUCCEEDED(hr))
{
   // Do stuff here.
}