Using the Active Desktop Object

[This feature is supported only under Windows XP or earlier. ]

This article contains information on the ActiveDesktop object that is part of the Windows Shell API. This object, through its IActiveDesktop interface, enables you to add, remove, and change items on the desktop.

Overview of the Active Desktop Interface

• Accessing the Active Desktop
• Adding a Desktop Item
• Enumerating the Desktop Items

The Active Desktop is a feature introduced with Microsoft Internet Explorer 4.0 that enables you to include HTML documents and items (such as Microsoft ActiveX Controls and Java applets) directly to your desktop. The IActiveDesktop interface, which is part of the Windows Shell API, is used to programmatically add, remove, and modify the items on the desktop. Active Desktop items can also be added using a Channel Definition Format (CDF) file.

Accessing the Active Desktop

To access the Active Desktop, a client application would need to create an instance of the ActiveDesktop object (CLSID_ActiveDesktop) with the CoCreateInstance function and retrieve a pointer to the object's IActiveDesktop interface.

The following sample shows how to retrieve a pointer to the IActiveDesktop interface.

HRESULT hr;
IActiveDesktop *pActiveDesktop;

//Create an instance of the Active Desktop
hr = CoCreateInstance(CLSID_ActiveDesktop, NULL, CLSCTX_INPROC_SERVER,
                      IID_IActiveDesktop, (void**)&pActiveDesktop);

//Insert code to call the IActiveDesktop methods

// Call the Release method
pActiveDesktop->Release();

Adding a Desktop Item

There are three methods you can use to add a desktop item: IActiveDesktop::AddDesktopItem, IActiveDesktop::AddDesktopItemWithUI, and IActiveDesktop::AddUrl. Each desktop item added to the Active Desktop must have a different source URL.

The IActiveDesktop::AddDesktopItemWithUI and IActiveDesktop::AddUrl methods both provide the option to display the various user interfaces that can be displayed before adding a desktop item to the Active Desktop. The interfaces verify whether users want to add the desktop item to their Active Desktop. The interfaces also notify users of any security risks that are warranted by the URL security zone settings, and they ask users if they would like to create a subscription for this desktop item. Both methods also provide a way of suppressing the user interfaces. The IActiveDesktop::AddDesktopItem method requires a call to IActiveDesktop::ApplyChanges in order to update the registry. For the IActiveDesktop::AddDesktopItemWithUI, the client application must immediately release the IActiveDesktop interface and then use the CoCreateInstance function to retrieve an interface to an instance of the ActiveDesktop object that includes the newly added desktop item.

The IActiveDesktop::AddDesktopItem method adds the specified desktop item to the Active Desktop without any user interface, unless the URL security zone settings prevent it. If the URL security zone settings do not allow the desktop item to be added without prompting the user, the method fails. IActiveDesktop::AddDesktopItem also requires a call to IActiveDesktop::ApplyChanges in order to update the registry.

The following sample demonstrates how to add a desktop item with the IActiveDesktop::AddDesktopItem method.

HRESULT hr;
IActiveDesktop *pActiveDesktop;
COMPONENT compDesktopItem;

//Create an instance of the Active Desktop
hr = CoCreateInstance(CLSID_ActiveDesktop, NULL, CLSCTX_INPROC_SERVER,
                      IID_IActiveDesktop, (void**)&pActiveDesktop);

// Initialize the COMPONENT structure
compDesktopItem.dwSize = sizeof(COMPONENT);

// Insert code that adds the information about the desktop item 
// to the COMPONENT structure

// Add the desktop item
pActiveDesktop->AddDesktopItem(&compDesktopItem,0);

// Save the changes to the registry
pActiveDesktop->ApplyChanges(AD_APPLY_ALL);

Enumerating the Desktop Items

To enumerate the desktop items currently installed on the Active Desktop, the client application needs to retrieve the total number of desktop items installed using the IActiveDesktop::GetDesktopItemCount method and then creating a loop that retrieves the COMPONENT structure for each desktop item by calling the IActiveDesktop::GetDesktopItem method using the desktop item index.

The following sample demonstrates one way to enumerate the desktop items.

HRESULT hr;
IActiveDesktop *pActiveDesktop;
COMPONENT compDesktopItem;
int intCount;
int intIndex = 0;

//Create an instance of the Active Desktop
hr = CoCreateInstance(CLSID_ActiveDesktop, NULL, CLSCTX_INPROC_SERVER,
                      IID_IActiveDesktop, (void**)&pActiveDesktop);

pActiveDesktop->GetDesktopItemCount(&intCount,0);

compDesktopItem.dwSize = sizeof(COMPONENT);

while(intIndex<=(intCount-1))
{
    //get the COMPONENT structure for the current desktop item
    pActiveDesktop->GetDesktopItem(intIndex, &compDesktopItem,0);

    //Insert code that processes the structure

    //Increment the index
    intIndex++;

    //Insert code to clean-up structure for next component
}

// Call the Release method
pActiveDesktop->Release();