Função GetProcessReference (shlwapi.h)

  • Artigo

Recupera o objeto específico do processo fornecido por SetProcessReference, incrementando a contagem de referências para manter o processo ativo.

Sintaxe

LWSTDAPI GetProcessReference(
  [out] IUnknown **punk
);

Parâmetros

[out] punk

O endereço de um ponteiro que, quando essa função retorna com êxito, aponta para o objeto fornecido ao processo por SetProcessReference. Seu aplicativo é responsável por liberar esse recurso quando ele não for mais necessário.

Um ponteiro para um IUnknown de thread livre. Os componentes podem usar essa interface (por meio de SHGetInstanceExplorer) para impedir que o processo de host seja encerrado. Esse valor pode ser NULL, caso em que a referência de processo não é mais disponibilizada para componentes.

Retornar valor

Nenhum

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 Windows Internet Explorer (Iexplore.exe). Normalmente, quando o usuário fecha o processo de host, o componente é desligado imediatamente também. Uma terminação tão abrupta 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.

GetProcessReference permite que os componentes executados em um processo de host mantenham uma referência no processo de host. GetProcessReference 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 seja fechado prematuramente. Depois que o componente tiver concluído o processamento necessário, ele deverá chamar (*punk)->Release para liberar a referência do host e permitir que o processo seja encerrado.

Nota Se GetProcessReference 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 *punk só pode ser usada para lançar essa referência. Os componentes não podem usar (*punk)->QueryInterface para solicitar outros ponteiros de interface.
 
GetProcessReference só terá êxito se for chamado de um aplicativo que anteriormente havia chamado SetProcessReference para definir uma referência de processo.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 8 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2012 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho shlwapi.h
Biblioteca Shlwapi.lib
DLL Api-ms-win-shcore-thread-L1-1-0.dll

Confira também

SHGetInstanceExplorer

SetProcessReference

Conjuntos de API do Windows