Функция 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 принимает подсчитываемую ссылку на этот объект. Диспетчер ввода-вывода позже выпускает эту ссылку при выходе из потока. Дополнительные сведения см. в подразделе "Примечания".

[out] ThreadHandle

Указатель на переменную, в которую подпрограмма записывает дескриптор ядра для созданного потока. Если дескриптор больше не нужен, драйвер должен закрыть дескриптор, вызвав подпрограмму ZwClose .

[in] DesiredAccess

Значение ACCESS_MASK , представляющее типы доступа, которые вызывающий объект запрашивает к созданному потоку.

[in, optional] ObjectAttributes

Указатель на структуру OBJECT_ATTRIBUTES , указывающую атрибуты объекта потока. Атрибуты OBJ_PERMANENT, OBJ_EXCLUSIVE и OBJ_OPENIF недопустимы для объекта потока. Если вызывающий объект не выполняется в контексте системного процесса, он должен задать атрибут OBJ_KERNEL_HANDLE в структуре OBJECT_ATTRIBUTES .

[in, optional] ProcessHandle

Открытый дескриптор для процесса, в адресном пространстве которого будет выполняться созданный поток. Поток вызывающего объекта должен иметь PROCESS_CREATE_THREAD доступ к этому процессу. Если этот параметр имеет значение NULL, поток будет создан в начальном системном процессе. Этот параметр должен иметь значение NULL для потока, созданного драйвером. Используйте макрос NtCurrentProcess , определенный в файле заголовка Wdm.h, чтобы указать текущий процесс.

[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) или контекста пользовательского режима и выполняется только в режиме ядра.

Как правило, драйвер вызывает IoCreateSystemThread либо при запуске устройства, либо когда подпрограммы DispatchXxx драйвера начинают получать запросы ввода-вывода. Например, драйвер может вызвать эту подпрограмму для создания потока, когда подпрограмма DispatchXxx получает асинхронный запрос на управление устройством.

Если параметр ProcessHandle имеет значение NULL, созданный поток связывается с системным процессом. Такой поток продолжает выполняться до тех пор, пока система не завершит работу или не завершит работу потока.

Подпрограммы драйвера, которые выполняются в контексте процесса, отличном от контекста системного процесса, должны задать атрибут OBJ_KERNEL_HANDLE для параметра ObjectAttributesобъекта IoCreateSystemThread. Этот атрибут ограничивает использование дескриптора, возвращаемого IoCreateSystemThread , процессами, работающими в режиме ядра. В противном случае дескриптор потока может получить доступ к процессу, в контексте которого выполняется драйвер. Драйверы могут вызывать макрос InitializeObjectAttributes , чтобы задать атрибут OBJ_KERNEL_HANDLE в атрибутах объекта, как показано в следующем примере кода.

OBJECT_ATTRIBUTES ObjectAttributes;

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

IoCreateSystemThread похожа на подпрограмму PsCreateSystemThread , но имеет дополнительный параметр IoObject, который является указателем на объект драйвера или объект устройства вызывающего объекта. IoCreateSystemThread использует этот параметр, чтобы гарантировать, что драйвер не может выгрузить, пока существует созданный поток. Перед планированием запуска StartRoutine в этом потоке IoCreateSystemThread принимает подсчитываемую ссылку на объект IoObject . Диспетчер ввода-вывода освобождает эту ссылку после выхода созданного потока. Таким образом, этот объект сохраняется в течение всего времени существования созданного потока.

В отличие от системного потока, созданного подпрограммой PsCreateSystemThread , поток, созданный IoCreateSystemThread , не вызывает подпрограмму PsTerminateSystemThread для завершения. Вместо этого диспетчер ввода-вывода вызывает PsTerminateSystemThread от имени созданного потока при выходе потока.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 8.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL