PsLookupThreadByThreadId function (ntifs.h)

The PsLookupThreadByThreadId routine accepts the thread ID of a thread and returns a referenced pointer to the ETHREAD structure of the thread.

Syntax

NTSTATUS PsLookupThreadByThreadId(
  [in]  HANDLE   ThreadId,
  [out] PETHREAD *Thread
);

Parameters

[in] ThreadId

Specifies the thread ID of the thread.

[out] Thread

Returns a referenced pointer to the ETHREAD structure of thread specified by the ThreadId.

Return value

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

Return code Description
STATUS_INVALID_PARAMETER
The thread ID was not found.

Remarks

This routine is available on Windows 2000 and later versions.

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

The ETHREAD 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 threads by calling PsLookupThreadByThreadId to convert a thread ID to an ETHREAD structure. The thread ID is available in the thread create routine. A file system filter driver can set a thread notification callback routine using PsSetCreateThreadNotifyRoutine. In the notification callback routine, the file system filter driver can use the passed in ThreadId parameter and call PsLookupThreadByThreadId to locate the ETHREAD structure.

The PsLookupThreadByThreadId routine contains pageable code.

Requirements

Requirement Value
Target Platform Universal
Header ntifs.h (include Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= APC_LEVEL

See also

ObDereferenceObject

PsGetCurrentProcess

PsGetCurrentProcessId

PsGetCurrentThread

PsGetCurrentThreadId

PsLookupProcessByProcessId

PsRemoveCreateThreadNotifyRoutine

PsRemoveLoadImageNotifyRoutine

PsSetCreateThreadNotifyRoutine

PsSetLoadImageNotifyRoutine