Funzione PsLookupProcessByProcessId (ntifs.h)

Articolo
07/02/2025

La routine PsLookupProcessByProcessId accetta l'ID processo di un processo e restituisce un puntatore a cui si fa riferimento alla struttura EPROCESS del processo.

Sintassi

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

Parametri

[in] ProcessId

Specifica l'ID processo del processo.

[out] Process

Restituisce un puntatore a cui si fa riferimento alla struttura EPROCESS del processo specificato da ProcessId.

Valore restituito

PsLookupProcessByProcessId restituisce STATUS_SUCCESS in caso di esito positivo o di un valore NTSTATUS appropriato, ad esempio:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Specifica che in Windows XP e nelle versioni precedenti di Windows l'ID processo non è stato trovato.
STATUS_INVALID_CID	Specifica in Windows Vista e versioni successive di Windows l'ID client specificato non è valido.

Osservazioni

Questa routine è disponibile in Windows 2000 e versioni successive.

Se la chiamata a PsLookupProcessByProcessId ha esito positivo, PsLookupProcessByProcessID aumenta il conteggio dei riferimenti sull'oggetto restituito nel parametro processo. Di conseguenza, quando un driver è stato completato utilizzando il parametro Process, il driver deve chiamare ObDereferenceObject per dereferenziare il parametro process ricevuto dalla routine PsLookupProcessByProcess ID.

La struttura EPROCESS è una struttura di dati opaca usata internamente dal sistema operativo. Questa struttura può essere passata ad altre routine per accedere a informazioni specifiche in questa struttura.

Un driver di filtro del file system può enumerare i processi attivi e quindi chiamare PsLookupProcessByProcessId per convertire un ID processo in una struttura EPROCESS. L'ID processo è disponibile nella routine di creazione del processo. Un driver di filtro del file system può impostare una routine di callback di notifica del processo usando PsSetCreateProcessNotifyRoutine. Nella routine di callback di notifica il driver di filtro del file system può usare il parametro ProcessId passato e chiamare PsLookupProcessByProcessID per individuare la struttura EPROCESS. Il PsSetCreateThreadNotifyRoutine può essere usato anche per impostare una routine di notifica che restituisce l'ID processo quando viene creato un ID thread.

La routine PsLookupProcessByProcessId contiene codice pageable.