PsCreateSystemThread-Funktion (wdm.h)

Artikel
02/27/2024

Die PsCreateSystemThread-Routine erstellt einen Systemthread, der im Kernelmodus ausgeführt wird, und gibt ein Handle für den Thread zurück.

Syntax

NTSTATUS PsCreateSystemThread(
  [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

[out] ThreadHandle

Verweist auf eine Variable, die das Handle empfängt. Der Treiber muss das Handle mit ZwClose schließen, sobald das Handle nicht mehr verwendet wird. Dieses Handle ist ein Kernelhandle für Windows Vista und höhere Versionen von Windows. In früheren Versionen von Windows ist das Handle möglicherweise kein Kernelhandle.

[in] DesiredAccess

Gibt den ACCESS_MASK Wert an, der die angeforderten Zugriffstypen für den erstellten Thread darstellt.

[in, optional] ObjectAttributes

Verweist auf eine -Struktur, die die Attribute des Objekts angibt. OBJ_PERMANENT, OBJ_EXCLUSIVE und OBJ_OPENIF sind keine gültigen Attribute für ein Threadobjekt. Wenn der Aufrufer unter Windows XP und höheren Versionen von Windows nicht im Systemprozesskontext ausgeführt wird, muss er das attribut OBJ_KERNEL_HANDLE für ObjectAttributes festlegen. Treiber für Microsoft Windows 2000 und Windows 98/Me dürfen Nur PsCreateSystemThread aus dem Systemprozesskontext aufrufen. Für Windows Vista und höhere Versionen von Windows ist das Handle ein Kernelhandle.

[in, optional] ProcessHandle

Gibt ein geöffnetes Handle für den Prozess an, in dessen Adressraum der Thread ausgeführt werden soll. Der Thread des Aufrufers muss PROCESS_CREATE_THREAD Zugriff auf diesen Prozess haben. Wenn dieser Parameter nicht angegeben wird, wird der Thread im anfänglichen Systemprozess erstellt. Dieser Wert sollte null für einen vom Treiber erstellten Thread sein. Verwenden Sie das in Ntddk.h definierte NtCurrentProcess-Makro , um den aktuellen Prozess anzugeben.

[out, optional] ClientId

Verweist auf eine Struktur, die den Clientbezeichner des neuen Threads empfängt. Dieser Wert sollte null für einen vom Treiber erstellten Thread sein.

[in] StartRoutine

Der Einstiegspunkt für den neu erstellten Systemthread. Dieser Parameter ist ein Funktionszeiger auf eine ThreadStart-Routine , die ein einzelnes Argument empfängt, bei dem es sich um den vom Aufrufer angegebenen StartContext-Parameterwert handelt.

[in, optional] StartContext

Stellt ein einzelnes Argument bereit, das an den Thread übergeben wird, wenn mit der Ausführung begonnen wird.

Rückgabewert

PsCreateSystemThread gibt STATUS_SUCCESS zurück, wenn der Thread erstellt wurde.

Hinweise

Treiber, die dedizierte Gerätethreads erstellen, rufen diese Routine auf, entweder bei der Initialisierung oder wenn E/A-Anforderungen in die Dispatch-Routinen eines solchen Treibers eingehen. Beispielsweise kann ein Treiber einen solchen Thread erstellen, wenn er eine asynchrone Gerätesteuerungsanforderung empfängt.

PsCreateSystemThread erstellt einen Kernelmodusthread, der einen separaten Ausführungsthread innerhalb des Systems beginnt. Ein solcher Systemthread hat keinen TEB- oder Benutzermoduskontext und wird nur im Kernelmodus ausgeführt.

Wenn die ProcessHandle-EingabeNULL 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 sich selbst durch Aufrufen von PsTerminateSystemThread beendet.

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 PsCreateSystemThread festlegen. Dadurch wird die Verwendung des von PsCreateSystemThread zurückgegebenen Handles auf Prozesse beschränkt, 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 attribut OBJ_KERNEL_HANDLE wie folgt festlegen.

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

Weitere Informationen zum StartContext-Parameter finden Sie unter ThreadStart.

Der neu erstellte Systemthread wird in PASSIVE_LEVEL innerhalb einer kritischen Region mit deaktivierten normalen Kernel-APCs ausgeführt.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), IrqlPsPassive(wdm)