ISideShowCapabilities::GetCapability Method 

Provides a generic mechanism for querying specific device capabilities.

HRESULT GetCapability(
    REFPROPERTYKEY in_keyCapability,
    PROPVARIANT *inout_pValue
);

Parameters

in_keyCapability

[in] A PROPERTYKEY value that specifies the device characteristic to be retrieved.

out_pValue

[in, out] A pointer to a properly initialized PROPVARIANT structure in which the Windows SideShow platform returns the value of the characteristic specified by the in_keyCapability parameter.

Return Values

Possible values include, but are not limited to, those in the following table.

HRESULT value	Description
S_OK	Success, indicating that the requested characteristic has been returned in the inout_pValue parameter.
E_INVALIDARG	The value of the inout_pValue parameter is either NULL or does not point to a properly initialized PROPVARIANT structure.
E_OUTOFMEMORY	CoTaskMemAlloc failed to allocate the required memory.
E_FAIL	The Windows SideShow Platform is not properly initialized.

Remarks

Before calling this method, the Windows SideShow gadget should use the PropVariantInit function to properly initialize the PROPVARIANT structure that is passed by using the inout_pValue parameter.

A Windows SideShow gadget calls this method repeatedly to determine the complete set of capabilities associated with the corresponding device. Each call will specify a different PROPERTYKEY value for the in_keyCapability parameter, and will result in a data type corresponding to that parameter value to be returned by using the inout_pValue parameter.

The gadget must free any underlying memory that is returned through the inout_pValue parameter by using the PropVariantClear function before freeing the PROPVARIANT structure itself.

For information about the available device capability PROPERTYKEY values, see Device Capabilities.

Example

This example demonstrates how to retrieve several individual device capabilities (the device identifier, and the screen width and height), given a pointer to an ISideShowCapabilities interface. For an example of how to retrieve one such interface for each connected device, see ISideShowContentManager::GetDeviceCapabilities Method. Important aspects of this example include declaring, initializing, and clearing PROPVARIANT variables into which individual device capabilities will be written by the Windows SideShow platform, as well as verifying the type of the returned variant and assigning it to another non-variant variable.

HRESULT     hr;
PROPVARIANT vDeviceID;
PROPVARIANT vScreenWidth;
PROPVARIANT vScreenHeight;

//
// Call PropVariantInit to initialize the three variant
// variables that will be used to retrieve the corresponding
// device capabilities.
//
PropVariantInit(&vDeviceID);
PropVariantInit(&vScreenWidth);
PropVariantInit(&vScreenHeight);

//
// Call GetCapability to retrieve the device identifier using
// one of the pointers returned by a prior call to GetDevices,
// and check for failure, including whether the returned variant
// type is correct.
//
// SIDESHOW_CAPABILITY_DEVICE_ID is defined in the file WindowsSideShow.h.
//
hr = pIDeviceCapability->GetCapability(SIDESHOW_CAPABILITY_DEVICE_ID,
                                       &vDeviceID);

if ((SUCCEEDED(hr)) && (VT_LPWSTR == vDeviceID.vt))
{
    //
    // Do something with the returned device identifier. In
    // this example, it is copied to an out parameter of the
    // containing routine.
    //
    hr = wcscpy_s(pDeviceID, DeviceIDLength, vDeviceID.pwszVal);
}
else
{
    //
    // Handling of failures will be application-specific.
    //
    HandleFailure("GetCapability(DeviceID)", hr);
}

//
// Call GetCapability to retrieve the screen width of the device using
// one of the pointers returned by a prior call to GetDevices,
// and check for failure, including whether the returned variant
// type is correct.
//
// SIDESHOW_CAPABILITY_SCREEN_WIDTH is defined in the file WindowsSideShow.h.
//
hr = pIDeviceCapability->GetCapability(SIDESHOW_CAPABILITY_SCREEN_WIDTH,
                                       &vScreenWidth);

if ((SUCCEEDED(hr)) && (VT_UI2 == vScreenWidth.vt))
{
    //
    // Do something with the returned device screen width. In
    // this example, it is assigned to an out parameter of the
    // containing routine.
    //
    *pScreenWidth = vScreenWidth.uiVal;
}
else
{
    //
    // Handling of failures will be application-specific.
    //
    HandleFailure("GetCapability(width)", hr);
}


//
// Call GetCapability to retrieve the screen height of the device using
// one of the pointers returned by a prior call to GetDevices,
// and check for failure, including whether the returned variant
// type is correct.
//
// SIDESHOW_CAPABILITY_SCREEN_HEIGHT is defined in the file WindowsSideShow.h.
//
hr = pIDeviceCapability->GetCapability(SIDESHOW_CAPABILITY_SCREEN_HEIGHT,
                                       &vScreenHeight);

if ((SUCCEEDED(hr)) && (VT_UI2 == vScreenHeight.vt))
{
    //
    // Do something with the returned device screen height. In
    // this example, it is assigned to an out parameter of the
    // containing routine.
    //
    *pScreenHeight = vScreenHeight.uiVal;
}
else
{
    //
    // Handling of failures will be application-specific.
    //
    HandleFailure("GetCapability(height)", hr);
}

//
// Call PropVariantClear to release any memory associated
// with the returned variant variables.
//
PropVariantClear(&vDeviceID);
PropVariantClear(&vScreenWidth);
PropVariantClear(&vScreenHeight);

Applies To

ISideShowCapabilities

See Also

Concepts

ISideShowContent::GetContent Method
ISideShowContentManager::GetDeviceCapabilities Method
ISideShowEvents::ApplicationEvent Method
ISideShowEvents::DeviceAdded Method
ISideShowEvents::DeviceRemoved Method
Device Capabilities