Usando o objeto Da Área de Trabalho Ativa

  • Artigo

[Esse recurso só tem suporte no Windows XP ou anterior. ]

Este artigo contém informações sobre o objeto ActiveDesktop que faz parte da API do Shell do Windows. Esse objeto, por meio de sua interface IActiveDesktop , permite adicionar, remover e alterar itens na área de trabalho.

Visão geral da interface da área de trabalho ativa

A Área de Trabalho Ativa é um recurso introduzido com o Microsoft Internet Explorer 4.0 que permite incluir documentos e itens HTML (como controles Microsoft ActiveX e miniaplicativos Java) diretamente para sua área de trabalho. A interface IActiveDesktop , que faz parte da API do Shell do Windows, é usada para adicionar, remover e modificar programaticamente os itens na área de trabalho. Os itens da Área de Trabalho Ativa também podem ser adicionados usando um arquivo CDF (Formato de Definição de Canal).

Acessando a Área de Trabalho Ativa

Para acessar a Área de Trabalho Ativa, um aplicativo cliente precisaria criar uma instância do objeto ActiveDesktop (CLSID_ActiveDesktop) com a função CoCreateInstance e recuperar um ponteiro para a interface IActiveDesktop do objeto.

O exemplo a seguir mostra como recuperar um ponteiro para a interface 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();

Adicionando um item da área de trabalho

Há três métodos que você pode usar para adicionar um item da área de trabalho: IActiveDesktop::AddDesktopItem, IActiveDesktop::AddDesktopItemWithUI e IActiveDesktop::AddUrl. Cada item da área de trabalho adicionado à Área de Trabalho Ativa deve ter uma URL de origem diferente.

Os métodos IActiveDesktop::AddDesktopItemWithUI e IActiveDesktop::AddUrl fornecem a opção de exibir as várias interfaces do usuário que podem ser exibidas antes de adicionar um item da área de trabalho à Área de Trabalho Ativa. As interfaces verificam se os usuários desejam adicionar o item da área de trabalho à área de trabalho ativa. As interfaces também notificam os usuários sobre quaisquer riscos de segurança que são garantidos pelas configurações da zona de segurança da URL e perguntam aos usuários se eles gostariam de criar uma assinatura para este item da área de trabalho. Ambos os métodos também fornecem uma maneira de suprimir as interfaces do usuário. O método IActiveDesktop::AddDesktopItem requer uma chamada para IActiveDesktop::ApplyChanges para atualizar o registro. Para iActiveDesktop::AddDesktopItemWithUI, o aplicativo cliente deve liberar imediatamente a interface IActiveDesktop e, em seguida, usar a função CoCreateInstance para recuperar uma interface para uma instância do objeto ActiveDesktop que inclui o item de área de trabalho recém-adicionado.

O método IActiveDesktop::AddDesktopItem adiciona o item de área de trabalho especificado à Área de Trabalho Ativa sem nenhuma interface do usuário, a menos que as configurações da zona de segurança da URL o impeçam. Se as configurações da zona de segurança da URL não permitirem que o item da área de trabalho seja adicionado sem avisar o usuário, o método falhará. IActiveDesktop::AddDesktopItem também requer uma chamada para IActiveDesktop::ApplyChanges para atualizar o registro.

O exemplo a seguir demonstra como adicionar um item de área de trabalho com o 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);

Enumerando os itens da área de trabalho

Para enumerar os itens da área de trabalho atualmente instalados na Área de Trabalho Ativa, o aplicativo cliente precisa recuperar o número total de itens da área de trabalho instalados usando o método IActiveDesktop::GetDesktopItemCount e, em seguida, criar um loop que recupera a estrutura COMPONENT para cada item da área de trabalho chamando o método IActiveDesktop::GetDesktopItem usando o índice de item da área de trabalho.

O exemplo a seguir demonstra uma maneira de enumerar os itens da área de trabalho.

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