ISpObjectToken::IsUISupported (SAPI 5.4)

Article
08/26/2009

Microsoft Speech API 5.4

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

S_OK

S_FALSE

E_INVALIDARG

SPERR_UNINITIALIZED

SPERR_TOKEN_DELETED

FAILED(hr)

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

  
// 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.
}

Partager via