Função PsLookupProcessByProcessId (ntifs.h)

Artigo
02/26/2024

A rotina PsLookupProcessByProcessId aceita a ID do processo de um processo e retorna um ponteiro referenciado para a estrutura EPROCESS do processo.

Sintaxe

NTSTATUS PsLookupProcessByProcessId(
  [in]  HANDLE    ProcessId,
  [out] PEPROCESS *Process
);

Parâmetros

[in] ProcessId

Especifica a ID do processo.

[out] Process

Retorna um ponteiro referenciado para a estrutura EPROCESS do processo especificado por ProcessId.

Retornar valor

PsLookupProcessByProcessId retorna STATUS_SUCCESS com êxito ou um valor NTSTATUS apropriado, como:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	Especifica no Windows XP e em versões anteriores do Windows que a ID do processo não foi encontrada.
STATUS_INVALID_CID	Especifica no Windows Vista e versões posteriores do Windows que a ID do cliente especificada não é válida.

Comentários

Essa rotina está disponível no Windows 2000 e versões posteriores.

Se a chamada para PsLookupProcessByProcessId for bem-sucedida, PsLookupProcessByProcessID aumentará a contagem de referência no objeto retornado no parâmetro Process . Consequentemente, quando um driver for concluído usando o parâmetro Process , o driver deverá chamar ObDereferenceObject para desreferenciar o parâmetro Process recebido da rotina PsLookupProcessByProcessID .

A estrutura EPROCESS é uma estrutura de dados opaca usada internamente pelo sistema operacional. Essa estrutura pode ser passada para outras rotinas para acessar informações específicas nessa estrutura.

Um driver de filtro do sistema de arquivos pode enumerar processos ativos e chamar PsLookupProcessByProcessId para converter uma ID de processo em uma estrutura EPROCESS. A ID do processo está disponível na rotina de criação do processo. Um driver de filtro do sistema de arquivos pode definir uma rotina de retorno de chamada de notificação de processo usando PsSetCreateProcessNotifyRoutine. Na rotina de retorno de chamada de notificação, o driver de filtro do sistema de arquivos pode usar o parâmetro ProcessId passado e chamar PsLookupProcessByProcessID para localizar a estrutura EPROCESS. O PsSetCreateThreadNotifyRoutine também pode ser usado para definir uma rotina de notificação que retorna a ID do processo quando uma ID de thread é criada.

A rotina PsLookupProcessByProcessId contém código paginável.