ioCreateSystemThread 函数 (wdm.h)

项目
03/08/2023

IoCreateSystemThread 例程创建在内核模式下执行的系统线程，并为线程提供句柄。

语法

NTSTATUS IoCreateSystemThread(
  [in, out]       PVOID              IoObject,
  [out]           PHANDLE            ThreadHandle,
  [in]            ULONG              DesiredAccess,
  [in, optional]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional]  HANDLE             ProcessHandle,
  [out, optional] PCLIENT_ID         ClientId,
  [in]            PKSTART_ROUTINE    StartRoutine,
  [in, optional]  PVOID              StartContext
);

参数

[in, out] IoObject

指向要与创建的线程关联的 DEVICE_OBJECT 或 DRIVER_OBJECT 的指针。 IoCreateSystemThread 采用对此对象的计数引用。当线程退出时，I/O 管理器稍后会释放此引用。有关详细信息，请参阅“备注”。

[out] ThreadHandle

指向变量的指针，例程向其写入所创建线程的内核句柄。当不再需要句柄时，驱动程序必须通过调用 ZwClose 例程关闭句柄。

[in] DesiredAccess

ACCESS_MASK值，该值表示调用方向创建的线程请求的访问类型。

[in, optional] ObjectAttributes

指向 OBJECT_ATTRIBUTES 结构的指针，该结构指定线程对象的属性。 OBJ_PERMANENT、OBJ_EXCLUSIVE和OBJ_OPENIF属性不是线程对象的有效属性。如果调用方未在系统进程上下文中运行，则必须在 OBJECT_ATTRIBUTES 结构中设置 OBJ_KERNEL_HANDLE 属性。

[in, optional] ProcessHandle

进程的打开句柄，所创建的线程将运行其地址空间。调用方线程必须具有对此进程的PROCESS_CREATE_THREAD访问权限。如果此参数为 NULL，则将在初始系统进程中创建线程。对于驱动程序创建的线程，此参数应为 NULL 。使用 Wdm.h 头文件中定义的 NtCurrentProcess 宏指定当前进程。

[out, optional] ClientId

指向结构的指针，例程将创建的线程的客户端标识符写入到该结构。对于驱动程序创建的线程，此参数应为 NULL 。

[in] StartRoutine

指向 ThreadStart 例程的指针，该例程是所创建线程的入口点。

[in, optional] StartContext

当创建的线程开始运行时，作为 StartContext 参数传递给 ThreadStart 例程的上下文指针。

返回值

如果成功创建新线程，IoCreateSystemThread 将返回STATUS_SUCCESS。可能的返回值包括以下错误状态代码。

返回代码	说明
STATUS_INVALID_HANDLE	ProcessHandle 不是有效的进程句柄。
STATUS_PROCESS_IS_TERMINATING	ProcessHandle 指定的进程正在终止。
STATUS_INSUFFICIENT_RESOURCES	系统资源不足，无法执行请求的操作。

注解

从 Windows 8 开始，驱动程序可以调用 IoCreateSystemThread 来创建设备专用线程。此例程创建一个新的系统线程，该线程没有线程环境块 (TEB) 或用户模式上下文，并且仅在内核模式下运行。

通常，驱动程序在启动设备或驱动程序的 DispatchXxx 例程开始接收 I/O 请求时调用 IoCreateSystemThread。例如，当 DispatchXxx 例程收到异步设备控制请求时，驱动程序可能会调用此例程来创建线程。

如果 ProcessHandle 参数为 NULL，则创建的线程与系统进程相关联。此类线程将继续运行，直到系统关闭或线程退出。

在非系统进程上下文中运行的驱动程序例程必须为 IoCreateSystemThread 的 ObjectAttributes 参数设置 OBJ_KERNEL_HANDLE 属性。此属性将 IoCreateSystemThread 返回的句柄的使用限制为在内核模式下运行的进程。否则，线程句柄可由运行驱动程序的上下文中的进程访问。驱动程序可以调用 InitializeObjectAttributes 宏来设置对象属性中的 OBJ_KERNEL_HANDLE 属性，如以下代码示例所示。

OBJECT_ATTRIBUTES ObjectAttributes;

InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);

IoCreateSystemThread 类似于 PsCreateSystemThread 例程，但有一个附加参数 IoObject，它是指向调用方驱动程序对象或设备对象的指针。 IoCreateSystemThread 使用此参数来确保驱动程序在创建线程存在时无法卸载。在计划 StartRoutine 在此线程中运行之前， IoCreateSystemThread 会采用对 IoObject 对象的计数引用。 I/O 管理器在创建的线程退出后释放此引用。因此，此对象在创建的线程的生存期内保持不变。

与 PsCreateSystemThread 例程创建的系统线程不同， IoCreateSystemThread 创建的线程不调用 PsTerminateSystemThread 例程来终止自身。相反，当线程退出时，I/O 管理器代表创建的线程调用 PsTerminateSystemThread 。

要求

要求	值
最低受支持的客户端	从Windows 8开始可用。
目标平台	通用
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL