Uso del objeto de escritorio activo

[Esta característica solo se admite en Windows XP o versiones anteriores. ]

Este artículo contiene información sobre el objeto ActiveDesktop que forma parte de la API de Shell de Windows. Este objeto, a través de su interfaz IActiveDesktop , permite agregar, quitar y cambiar elementos en el escritorio.

Información general de la interfaz de escritorio activo

• Acceso al escritorio activo
• Agregar un elemento de escritorio
• Enumeración de los elementos de escritorio

El Escritorio activo es una característica introducida con Microsoft Internet Explorer 4.0 que permite incluir documentos y elementos HTML (como controles ActiveX de Microsoft y applets java) directamente en el escritorio. La interfaz IActiveDesktop , que forma parte de la API de Windows Shell, se usa para agregar, quitar y modificar los elementos en el escritorio mediante programación. Los elementos de Escritorio activo también se pueden agregar mediante un archivo de formato de definición de canal (CDF).

Acceso al escritorio activo

Para acceder a Active Desktop, una aplicación cliente tendría que crear una instancia del objeto ActiveDesktop (CLSID_ActiveDesktop) con la función CoCreateInstance y recuperar un puntero a la interfaz IActiveDesktop del objeto.

En el ejemplo siguiente se muestra cómo recuperar un puntero a la interfaz IActiveDesktop .

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();

Agregar un elemento de escritorio

Hay tres métodos que puede usar para agregar un elemento de escritorio: IActiveDesktop::AddDesktopItem, IActiveDesktop::AddDesktopItemWithUI e IActiveDesktop::AddUrl. Cada elemento de escritorio agregado al escritorio activo debe tener una dirección URL de origen diferente.

Los métodos IActiveDesktop::AddDesktopItemWithUI e IActiveDesktop::AddUrl proporcionan la opción de mostrar las distintas interfaces de usuario que se pueden mostrar antes de agregar un elemento de escritorio a Active Desktop. Las interfaces comprueban si los usuarios quieren agregar el elemento de escritorio a su escritorio activo. Las interfaces también notifican a los usuarios los riesgos de seguridad garantizados por la configuración de la zona de seguridad de la dirección URL y preguntan a los usuarios si quieren crear una suscripción para este elemento de escritorio. Ambos métodos también proporcionan una manera de suprimir las interfaces de usuario. El método IActiveDesktop::AddDesktopItem requiere una llamada a IActiveDesktop::ApplyChanges para actualizar el registro. Para IActiveDesktop::AddDesktopItemWithUI, la aplicación cliente debe liberar inmediatamente la interfaz IActiveDesktop y, a continuación, usar la función CoCreateInstance para recuperar una interfaz a una instancia del objeto ActiveDesktop que incluye el elemento de escritorio recién agregado.

El método IActiveDesktop::AddDesktopItem agrega el elemento de escritorio especificado al escritorio activo sin ninguna interfaz de usuario, a menos que la configuración de la zona de seguridad de la dirección URL lo impida. Si la configuración de la zona de seguridad de la dirección URL no permite agregar el elemento de escritorio sin preguntar al usuario, se produce un error en el método. IActiveDesktop::AddDesktopItem también requiere una llamada a IActiveDesktop::ApplyChanges para actualizar el registro.

En el ejemplo siguiente se muestra cómo agregar un elemento de escritorio con el método IActiveDesktop::AddDesktopItem .

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);

Enumeración de los elementos de escritorio

Para enumerar los elementos de escritorio instalados actualmente en Active Desktop, la aplicación cliente debe recuperar el número total de elementos de escritorio instalados mediante el método IActiveDesktop::GetDesktopItemCount y, a continuación, crear un bucle que recupere la estructura COMPONENT para cada elemento de escritorio llamando al método IActiveDesktop::GetDesktopItem mediante el índice del elemento de escritorio.

En el ejemplo siguiente se muestra una manera de enumerar los elementos de escritorio.

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();