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 |
|---|---|
|
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
PsRemoveCreateThreadNotifyRoutine
PsRemoveLoadImageNotifyRoutine