Fungsi IoCreateSystemThread (wdm.h)

Artikel
03/08/2023

Rutinitas IoCreateSystemThread membuat utas sistem yang dijalankan dalam mode kernel, dan memasok handel untuk utas.

Sintaks

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

Penunjuk ke DEVICE_OBJECT atau DRIVER_OBJECT untuk dikaitkan dengan utas yang dibuat. IoCreateSystemThread mengambil referensi yang dihitung ke objek ini. Manajer I/O kemudian merilis referensi ini ketika utas keluar. Untuk informasi selengkapnya, lihat Keterangan.

[out] ThreadHandle

Penunjuk ke variabel tempat rutin menulis handel kernel untuk utas yang dibuat. Ketika handel tidak lagi diperlukan, driver harus menutup handel dengan memanggil rutinitas ZwClose .

[in] DesiredAccess

Nilai ACCESS_MASK yang mewakili jenis akses permintaan pemanggil ke utas yang dibuat.

[in, optional] ObjectAttributes

Penunjuk ke struktur OBJECT_ATTRIBUTES yang menentukan atribut objek utas. Atribut OBJ_PERMANENT, OBJ_EXCLUSIVE, dan OBJ_OPENIF bukan atribut yang valid untuk objek utas. Jika penelepon tidak berjalan dalam konteks proses sistem, pemanggil harus mengatur atribut OBJ_KERNEL_HANDLE dalam struktur OBJECT_ATTRIBUTES .

[in, optional] ProcessHandle

Handel terbuka untuk proses di ruang alamat yang utas yang dibuat akan dijalankan. Utas pemanggil harus memiliki akses PROCESS_CREATE_THREAD ke proses ini. Jika parameter ini NULL, utas akan dibuat dalam proses sistem awal. Parameter ini harus NULL untuk utas yang dibuat driver. Gunakan makro NtCurrentProcess, yang ditentukan dalam file header Wdm.h, untuk menentukan proses saat ini.

[out, optional] ClientId

Penunjuk ke struktur tempat rutin menulis pengidentifikasi klien untuk utas yang dibuat. Parameter ini harus NULL untuk utas yang dibuat driver.

[in] StartRoutine

Penunjuk ke rutinitas ThreadStart yang merupakan titik masuk untuk utas yang dibuat.

[in, optional] StartContext

Penunjuk konteks yang diteruskan sebagai parameter StartContext ke rutinitas ThreadStart saat utas yang dibuat mulai berjalan.

Nilai kembali

IoCreateSystemThread mengembalikan STATUS_SUCCESS jika utas baru berhasil dibuat. Nilai yang mungkin dikembalikan termasuk kode status kesalahan berikut.

Menampilkan kode	Deskripsi
STATUS_INVALID_HANDLE	ProcessHandle bukan handel proses yang valid.
STATUS_PROCESS_IS_TERMINATING	Proses yang ditentukan oleh ProcessHandle berakhir.
STATUS_INSUFFICIENT_RESOURCES	Sumber daya sistem tidak cukup tersedia untuk melakukan operasi yang diminta.

Keterangan

Dimulai dengan Windows 8, driver dapat memanggil IoCreateSystemThread untuk membuat utas khusus perangkat. Rutinitas ini membuat utas sistem baru yang tidak memiliki blok lingkungan utas (TEB) atau konteks mode pengguna, dan hanya berjalan dalam mode kernel.

Biasanya, driver memanggil IoCreateSystemThread baik ketika memulai perangkat, atau ketika rutinitas DispatchXxx driver mulai menerima permintaan I/O. Misalnya, driver mungkin memanggil rutinitas ini untuk membuat utas ketika rutinItas DispatchXxx menerima permintaan kontrol perangkat asinkron.

Jika parameter ProcessHandle adalah NULL, utas yang dibuat dikaitkan dengan proses sistem. Utas seperti itu terus berjalan sampai sistem dimatikan atau utas keluar.

Rutinitas driver yang berjalan dalam konteks proses selain proses sistem harus mengatur atribut OBJ_KERNEL_HANDLE untuk parameter ObjectAttributes dari IoCreateSystemThread. Atribut ini membatasi penggunaan handel yang dikembalikan oleh IoCreateSystemThread untuk memproses yang berjalan dalam mode kernel. Jika tidak, handel utas dapat diakses oleh proses yang konteksnya driver berjalan. Driver dapat memanggil makro InitializeObjectAttributes untuk mengatur atribut OBJ_KERNEL_HANDLE dalam atribut objek, seperti yang ditunjukkan dalam contoh kode berikut.

OBJECT_ATTRIBUTES ObjectAttributes;

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

IoCreateSystemThread mirip dengan rutinitas PsCreateSystemThread , tetapi memiliki parameter tambahan, IoObject, yang merupakan penunjuk ke objek driver atau objek perangkat pemanggil. IoCreateSystemThread menggunakan parameter ini untuk memastikan bahwa driver tidak dapat membongkar saat utas yang dibuat ada. Sebelum menjadwalkan StartRoutine untuk berjalan di utas ini, IoCreateSystemThread mengambil referensi yang dihitung ke objek IoObject . Manajer I/O merilis referensi ini setelah utas yang dibuat keluar. Dengan demikian, objek ini bertahan selama masa pakai utas yang dibuat.

Berbeda dengan utas sistem yang dibuat oleh rutinitas PsCreateSystemThread , utas yang dibuat oleh IoCreateSystemThread tidak memanggil rutinitas PsTerminateSystemThread untuk mengakhiri dirinya sendiri. Sebaliknya, manajer I/O memanggil PsTerminateSystemThread atas nama utas yang dibuat saat utas keluar.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dimulai dengan Windows 8.
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL