PsLookupProcessByProcessId function

The PsLookupProcessByProcessId routine accepts the process ID of a process and returns a referenced pointer to EPROCESS structure of the process.

Syntax

C++

NTSTATUS PsLookupProcessByProcessId(
  HANDLE    ProcessId,
  PEPROCESS *Process
);

Parameters

ProcessId

Specifies the process ID of the process.

Process

Returns a referenced pointer to the EPROCESS structure of process specified by ProcessId.

Return Value

PsLookupProcessByProcessId returns STATUS_SUCCESS on success or an appropriate NTSTATUS value, such as:

Remarks

This routine is available on Windows 2000 and later versions.

If the call to PsLookupProcessByProcessId is successful, PsLookupProcessByProcessID increases the reference count on the object returned in the Process parameter. Consequently, when a driver has completed using the Process parameter, the driver must call ObDereferenceObject to dereference the Process parameter received from the PsLookupProcessByProcessID routine.

The EPROCESS structure is an opaque data structure used internally by the operating system. This structure can be passed to other routines to access specific information in this structure.

A file system filter driver can enumerate active processes and then call PsLookupProcessByProcessId to convert a process ID to an EPROCESS structure. The process ID is available in the process create routine. A file system filter driver can set a process notification callback routine using PsSetCreateProcessNotifyRoutine. In the notification callback routine, the file system filter driver can use the passed in ProcessId parameter and call PsLookupProcessByProcessID to locate the EPROCESS structure. The PsSetCreateThreadNotifyRoutine can also be used to set a notification routine that returns the process ID when a thread ID is created.

The PsLookupProcessByProcessId routine contains pageable code.

Requirements

See Also

ObDereferenceObject

PsGetCurrentProcess

PsGetCurrentProcessId

PsGetCurrentThread

PsGetCurrentThreadId

PsLookupThreadByThreadId

PsRemoveCreateThreadNotifyRoutine

PsRemoveLoadImageNotifyRoutine

PsSetCreateProcessNotifyRoutine

PsSetLoadImageNotifyRoutine