Функция IoCreateSystemThread (wdm.h)
Подпрограмма 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 Thread Start, когда создается поток начинает выполняться.
Возвращаемое значение
IoCreateSystemThread возвращает STATUS_SUCCESS, если новый поток был успешно создан. Возможные возвращаемые значения включают следующие коды состояния ошибки.
| Возвращаемый код | Описание |
|---|---|
| STATUS_INVALID_HANDLE | ProcessHandle не является допустимым дескриптором процесса. |
| STATUS_PROCESS_IS_TERMINATING | Процесс, указанный ProcessHandle, завершается. |
| STATUS_INSUFFICIENT_RESOURCES | Недостаточно системных ресурсов для выполнения запрошенной операции. |
Замечания
Начиная с Windows 8 драйвер может вызывать IoCreateSystemThread для создания выделенного устройства потока. Эта подпрограмма создает новый системный поток без блока среды потоков (TEB) или контекста пользовательского режима и выполняется только в режиме ядра.
Как правило, драйвер вызывает IoCreateSystemThread при запуске устройства или когда диспетчераXxx начинают получать запросы ввода-вывода. Например, драйвер может вызвать эту подпрограмму для создания потока, когда подпрограмма DispatchXxx получает асинхронный запрос на управление устройствами.
Если параметр ProcessHandleNULL, созданный поток связан с системным процессом. Такой поток продолжает работать до завершения работы системы или выхода потока.
Подпрограммы драйверов, выполняемые в контексте процесса, отличные от системного процесса, должны задать атрибут OBJ_KERNEL_HANDLE для параметра ObjectAttributesIoCreateSystemThread. Этот атрибут ограничивает использование дескриптора, возвращаемого 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 (include Wdm.h, Ntddk.h, Ntifs.h) |
| библиотеки | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |