IoCreateSystemThread-Funktion (wdm.h)
Die IoCreateSystemThread Routine erstellt einen Systemthread, der im Kernelmodus ausgeführt wird, und stellt einen 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 sollen. IoCreateSystemThread nimmt einen gezählten Verweis auf dieses Objekt an. 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 der Handle nicht mehr benötigt wird, muss der Treiber den Handle schließen, indem er die ZwClose Routine aufruft.
[in] DesiredAccess
Der ACCESS_MASK Wert, der die Zugriffstypen der Aufruferanforderungen an den erstellten Thread darstellt.
[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 ungültige Attribute für ein Threadobjekt. Wenn der Aufrufer nicht im Systemprozesskontext ausgeführt wird, muss es das OBJ_KERNEL_HANDLE-Attribut in der OBJECT_ATTRIBUTES-Struktur festlegen.
[in, optional] ProcessHandle
Ein geöffnetes Handle für den Prozess, 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 NULL- für einen vom Treiber erstellten Thread sein. Verwenden Sie das NtCurrentProcess Makro, das in der Wdm.h-Headerdatei definiert ist, 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 NULL- für einen vom Treiber erstellten Thread 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 gestartet wird.
Rückgabewert
IoCreateSystemThread- gibt STATUS_SUCCESS zurück, wenn der neue Thread erfolgreich erstellt wurde. Mögliche Rückgabewerte sind die folgenden Fehlerstatuscodes.
| Rückgabecode | Beschreibung |
|---|---|
| STATUS_INVALID_HANDLE | ProcessHandle- ist kein gültiger Prozesshandle. |
| STATUS_PROCESS_IS_TERMINATING | Der durch ProcessHandle- angegebene Prozess wird beendet. |
| STATUS_INSUFFICIENT_RESOURCES | Unzureichende Systemressourcen sind verfügbar, um den angeforderten Vorgang auszuführen. |
Bemerkungen
Ab Windows 8 kann ein Treiber IoCreateSystemThread- aufrufen, um einen gerätededizierten Thread zu erstellen. Diese Routine erstellt einen neuen Systemthread ohne Threadumgebungsblock (TEB) oder Benutzermoduskontext und wird nur im Kernelmodus ausgeführt.
In der Regel ruft der Treiber IoCreateSystemThread entweder beim Starten des Geräts oder beim Start des Treibers DispatchXxx-Routinen an, um 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 Parameter NULL-ist, wird der erstellte Thread dem Systemprozess zugeordnet. Ein solcher Thread wird weiterhin 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 IoCreateSystemThreadfestlegen. Dieses Attribut beschränkt die Verwendung des von IoCreateSystemThread zurückgegebenen Handle auf Prozesse, die im Kernelmodus ausgeführt werden. Andernfalls kann auf das Threadhandle durch den Prozess zugegriffen werden, in dessen Kontext der Treiber ausgeführt wird. 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 jedoch über einen zusätzlichen Parameter, IoObject, ein Zeiger auf das Treiberobjekt oder Geräteobjekt des Aufrufers. IoCreateSystemThread verwendet diesen Parameter, um sicherzustellen, dass der Treiber nicht entladen kann, während der erstellte Thread vorhanden ist. Vor der Planung StartRoutine- für die Ausführung in diesem Thread verwendet IoCreateSystemThread einen gezählten Verweis auf das IoObject--Objekt. Der E/A-Manager gibt diesen Verweis 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 nicht die PsTerminateSystemThread Routine 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 |
|---|---|
| mindestens unterstützte Client- | Verfügbar ab Windows 8. |
| Zielplattform- | Universal |
| Header- | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | PASSIVE_LEVEL |