Função SHGetInstanceExplorer (shlobj_core.h)

  • Artigo

Recupera uma interface que permite que extensões do Shell hospedadas e outros componentes impeçam que o processo de host seja fechado prematuramente. Normalmente, o processo de host é Explorer do Windows ou Explorer da Internet do Windows, mas essa função também pode ser usada por outros aplicativos.

Sintaxe

SHSTDAPI SHGetInstanceExplorer(
  [out] IUnknown **ppunk
);

Parâmetros

[out] ppunk

Tipo: IUnknown**

Quando essa função retorna com êxito, contém o endereço do ponteiro de interface IUnknown do processo de host. Essa é uma interface de thread livre usada para impedir que o processo de host seja encerrado. Se a chamada de função falhar, esse valor será definido como NULL.

Retornar valor

Tipo: HRESULT

Se essa função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

Há vários componentes, como manipuladores de extensão do Shell, que são implementados como DLLs e executados em um processo de host, como o Windows Explorer (Explorer.exe) ou o Explorer da Internet (Iexplore.exe). Normalmente, quando o usuário fecha o processo de host, o componente também é desligado imediatamente. Esse encerramento abrupto pode criar problemas para alguns componentes. Por exemplo, se um componente estiver usando um thread em segundo plano para baixar dados ou executar funções de interface do usuário, talvez seja necessário mais tempo para se desligar com segurança.

SHGetInstanceExplorer permite que os componentes executados em um processo de host mantenham uma referência no processo de host. SHGetInstanceExplorer incrementa a contagem de referência do host e retorna um ponteiro para a interface IUnknown do host. Ao manter essa referência, um componente pode impedir que o processo de host feche prematuramente. Depois que o componente tiver concluído o processamento necessário, ele deverá chamar (*ppunk)->Release para liberar a referência do host e permitir que o processo seja encerrado.

Nota Se SHGetInstanceExplorer for bem-sucedido, o componente deverá liberar a referência do host quando ele não for mais necessário. Caso contrário, todos os recursos associados ao processo permanecerão na memória. A interface IUnknown apontada por *ppunk só pode ser usada para liberar essa referência. Os componentes não podem usar (*ppunk)->QueryInterface para solicitar outros ponteiros de interface.
 
SHGetInstanceExplorer só terá êxito se for chamado de um aplicativo que anteriormente havia chamado SHSetInstanceExplorer para definir uma referência de processo.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho shlobj_core.h (inclua Shlobj.h)
Biblioteca Shell32.lib
DLL Shell32.dll (versão 4.0 ou posterior)