IoCreateSystemThread-Funktion (wdm.h)

Artikel
03/08/2023

Die IoCreateSystemThread-Routine erstellt einen Systemthread, der im Kernelmodus ausgeführt wird, und stellt ein Handle für den Thread bereit.

Syntax

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
);

Parameter

[in, out] IoObject

Ein Zeiger auf die DEVICE_OBJECT oder DRIVER_OBJECT , die dem erstellten Thread zugeordnet werden soll. IoCreateSystemThread akzeptiert einen gezählten Verweis auf dieses Objekt. Der E/A-Manager gibt diesen Verweis später frei, wenn der Thread beendet wird. Weitere Informationen finden Sie in den Hinweisen.

[out] ThreadHandle

Ein Zeiger auf eine Variable, in die die Routine das Kernelhandle für den erstellten Thread schreibt. Wenn das Handle nicht mehr benötigt wird, muss der Treiber das Handle durch Aufrufen der ZwClose-Routine schließen.

[in] DesiredAccess

Der ACCESS_MASK Wert, der die Zugriffstypen darstellt, die der Aufrufer an den erstellten Thread anfordert.

[in, optional] ObjectAttributes

Ein Zeiger auf eine OBJECT_ATTRIBUTES-Struktur , die die Attribute des Threadobjekts angibt. Die Attribute OBJ_PERMANENT, OBJ_EXCLUSIVE und OBJ_OPENIF sind keine gültigen Attribute für ein Threadobjekt. Wenn der Aufrufer nicht im Systemprozesskontext ausgeführt wird, muss er das attribut OBJ_KERNEL_HANDLE in der OBJECT_ATTRIBUTES-Struktur festlegen.

[in, optional] ProcessHandle

Ein geöffnetes Handle für den Prozess, in dessen Adressraum der erstellte Thread ausgeführt werden soll. Der Thread des Aufrufers muss PROCESS_CREATE_THREAD Zugriff auf diesen Prozess haben. Wenn dieser Parameter NULL ist, wird der Thread im anfänglichen Systemprozess erstellt. Dieser Parameter sollte für einen vom Treiber erstellten Thread NULL sein. Verwenden Sie das In der Wdm.h-Headerdatei definierte NtCurrentProcess-Makro , um den aktuellen Prozess anzugeben.

[out, optional] ClientId

Ein Zeiger auf eine Struktur, in die die Routine den Clientbezeichner für den erstellten Thread schreibt. Dieser Parameter sollte für einen vom Treiber erstellten Thread NULL sein.

[in] StartRoutine

Ein Zeiger auf eine ThreadStart-Routine , die der Einstiegspunkt für den erstellten Thread ist.

[in, optional] StartContext

Ein Kontextzeiger, der als StartContext-Parameter an die ThreadStart-Routine übergeben wird, wenn der erstellte Thread ausgeführt wird.

Rückgabewert

IoCreateSystemThread gibt STATUS_SUCCESS zurück, wenn der neue Thread erfolgreich erstellt wurde. Mögliche Rückgabewerte sind der folgende Fehler status Codes.

Rückgabecode	Beschreibung
STATUS_INVALID_HANDLE	ProcessHandle ist kein gültiges Prozesshandle.
STATUS_PROCESS_IS_TERMINATING	Der von ProcessHandle angegebene Prozess wird beendet.
STATUS_INSUFFICIENT_RESOURCES	Es sind nicht genügend Systemressourcen verfügbar, um den angeforderten Vorgang auszuführen.

Hinweise

Ab Windows 8 kann ein Treiber IoCreateSystemThread aufrufen, um einen dedizierten Gerätethread zu erstellen. Diese Routine erstellt einen neuen Systemthread, der keinen Threadumgebungsblock (TEB) oder Benutzermoduskontext aufweist und nur im Kernelmodus ausgeführt wird.

In der Regel ruft der Treiber IoCreateSystemThread auf, wenn er das Gerät startet oder wenn die Dispatch-Xxx-Routinen des Treibers beginnen, E/A-Anforderungen zu empfangen. Beispielsweise kann ein Treiber diese Routine aufrufen, um einen Thread zu erstellen, wenn eine DispatchXxx-Routine eine asynchrone Gerätesteuerungsanforderung empfängt.

Wenn der ProcessHandle-ParameterNULL ist, wird der erstellte Thread dem Systemprozess zugeordnet. Ein solcher Thread wird so lange ausgeführt, bis entweder das System heruntergefahren wird oder der Thread beendet wird.

Treiberroutinen, die in einem anderen Prozesskontext als dem des Systemprozesses ausgeführt werden, müssen das attribut OBJ_KERNEL_HANDLE für den ObjectAttributes-Parameter von IoCreateSystemThread festlegen. Dieses Attribut schränkt die Verwendung des von IoCreateSystemThread zurückgegebenen Handles auf Prozesse ein, die im Kernelmodus ausgeführt werden. Andernfalls kann der Prozess, in dessen Kontext der Treiber ausgeführt wird, auf das Threadhandle zugreifen. Treiber können das InitializeObjectAttributes-Makro aufrufen, um das attribut OBJ_KERNEL_HANDLE in den Objektattributen festzulegen, wie im folgenden Codebeispiel gezeigt.

OBJECT_ATTRIBUTES ObjectAttributes;

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

IoCreateSystemThread ähnelt der PsCreateSystemThread-Routine , verfügt aber über einen zusätzlichen Parameter, IoObject, der einen Zeiger auf das Treiber- oder Geräteobjekt des Aufrufers darstellt. IoCreateSystemThread verwendet diesen Parameter, um sicherzustellen, dass der Treiber nicht entladen kann, solange der erstellte Thread vorhanden ist. Bevor Die Ausführung von StartRoutine in diesem Thread geplant wird, verwendet IoCreateSystemThread einen gezählten Verweis auf das IoObject-Objekt . Der E/A-Manager gibt diese Referenz frei, nachdem der erstellte Thread beendet wurde. Daher wird dieses Objekt für die Lebensdauer des erstellten Threads beibehalten.

Im Gegensatz zu einem Systemthread, der von der PsCreateSystemThread-Routine erstellt wird, ruft ein von IoCreateSystemThread erstellter Thread die PsTerminateSystemThread-Routine nicht auf, um sich selbst zu beenden. Stattdessen ruft der E/A-Manager PsTerminateSystemThread im Namen des erstellten Threads auf, wenn der Thread beendet wird.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 8.
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL