ISideShowContentManager::GetDeviceCapabilities Method 

Retrieves a collection of ISideShowCapabilities objects that represent each device for which the Windows SideShow gadget is providing content.

Declaration

[C++]

HRESULT GetDeviceCapabilities(
    [out]    ISideShowCapabilitiesCollection **out_ppCollection
);

Parameters

out_ppCollection

[out] A pointer into which the Windows SideShow platform will write the address of an ISideShowCapabilitiesCollection interface pointer. For more information, see the Remarks section later in this topic.

Return Values

Remarks

The ISideShowContentManager::GetDeviceCapabilities Method provides a way for the Windows SideShow gadget to determine how many devices have been configured for it to display content upon, and the capabilities of those devices.

If more than one device is available to the gadget, and especially if the devices have different capabilities, the Windows SideShow gadget can then generate different content for different devices as appropriate.

If there are no devices available, the collection is empty.

When this method returns successfully, with a return value of S_OK, the out_ppCollection parameter contains a pointer to a capabilities collection interface for the attached devices which have been authorized for the gadget.

Example

This example demonstrates how Windows SideShow gadgets can retrieve information about the devices on which they are currently displaying content. The example shows how to retrieve the ISideShowCapabilitiesCollection interface and enumerate all ISideShowCapabilities interfaces it contains. For each ISideShowCapabilities object it retrieves, it calls the client-specific routine GetDeviceCapabilities to retrieve certain device capabilities. For details about retrieving individual capabilities, see the example for the ISideShowCapabilities::GetCapability Method method. Another client-specific routine, StoreDeviceCapabilities, exists in this example to show that most Windows SideShow gadgets do something with the capabilities that they retrieve. Finally, this example shows how to properly release all interface pointers used during the enumeration.

[C++]

HRESULT hr;
ISideShowCapabilitiesCollection* pICapabilitiesCollection = NULL;

//
// Call GetDeviceCapabilities using the previously established pointer
// to the ContentManager object and check for failures.
// If successful, this call will return a pointer
// to an ISideShowCapabilitiesCollection interface.
//
hr = pISideShowContentManager->GetDeviceCapabilities(&pICapabilitiesCollection);
if (SUCCEEDED(hr) && NULL != pICapabilitiesCollection)
{
    DWORD NumDevices = 0;
    ISideShowCapabilities* pIDeviceCapabilities = NULL;
    
    hr = pICapabilitiesCollection->GetCount(&NumDevices);
    if (SUCCEEDED(hr) && NumDevices != 0)
    {
        for (DWORD Index = 0; Index < NumDevices; ++Index)
        {
            hr = pICapabilitiesCollection->GetAt(Index, &pIDeviceCapabilities);
            if (SUCCEEDED(hr) && NULL != pIDeviceCapabilities)
            {
                WCHAR DeviceIdentifier[MAX_PATH];
                unsigned short ScreenWidth;
                unsigned short ScreenHeight;

                //
                // Call a routine that will retrieve several individual
                // device capabilities. This routine will call
                // GetCapability once for each of the capabilities it
                // is meant to retrieve.
                //
                GetDeviceCapabilities(pIDeviceCapabilities, 
                                      DeviceIdentifier,
                                      MAX_PATH,
                                      &ScreenHeight, 
                                      &ScreenWidth);

                //
                // Call an application-specific routine to do something
                // with the retrieved capabilities.
                //
                StoreDeviceCapabilities(DeviceIdentifier,
                                        ScreenHeight, 
                                        ScreenWidth);

                //
                // Release the ISideShowCapabilities interface pointer.
                //
                pIDeviceCapabilities->Release();
                pIDeviceCapabilities = NULL;
            }
        }
    }

    //
    // Release the ISideShowCapabilitiesCollection interface pointer.
    //
    pICapabilitiesCollection->Release();
    pICapabilitiesCollection = NULL;
}
else
{
    //
    // Handling of failures will be application-specific.
    //
    HandleFailure("GetDeviceCapabilities", hr);
}

Applies To

ISideShowContentManager

See Also

Concepts

ISideShowCapabilities
ISideShowCapabilitiesCollection