IoCreateSystemThread 関数 (wdm.h)

[アーティクル]
03/08/2023

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 は、このオブジェクトへのカウントされた参照を受け取ります。 I/O マネージャーは、後でスレッドが終了したときにこの参照を解放します。詳細については、「解説」を参照してください。

[out] ThreadHandle

ルーチンが作成されたスレッドのカーネルハンドルを書き込む変数へのポインター。ハンドルが不要になった場合、ドライバーは ZwClose ルーチンを呼び出してハンドルを閉じる必要があります。

[in] DesiredAccess

呼び出し元が作成したスレッドに対して要求するアクセスの種類を表すACCESS_MASK値。

[in, optional] ObjectAttributes

スレッドオブジェクトの属性を指定する OBJECT_ATTRIBUTES 構造体へのポインター。 OBJ_PERMANENT、OBJ_EXCLUSIVE、およびOBJ_OPENIF属性は、スレッドオブジェクトに対して有効な属性ではありません。呼び出し元がシステムプロセスコンテキストで実行されていない場合は、 OBJECT_ATTRIBUTES構造体で OBJ_KERNEL_HANDLE 属性を設定する必要があります。

[in, optional] ProcessHandle

作成されたスレッドのアドレス空間を実行するプロセスのオープンハンドル。呼び出し元のスレッドは、このプロセスにPROCESS_CREATE_THREADアクセスできる必要があります。このパラメーターが NULL の場合、スレッドは初期システムプロセスで作成されます。このパラメーターは、ドライバーによって作成されたスレッドの 場合は NULL である 必要があります。 Wdm.h ヘッダーファイルで定義されている NtCurrentProcess マクロを使用して、現在のプロセスを指定します。

[out, optional] ClientId

ルーチンが作成されたスレッドのクライアント識別子を書き込む構造体へのポインター。このパラメーターは、ドライバーによって作成されたスレッドの 場合は NULL である 必要があります。

[in] StartRoutine

作成されたスレッドのエントリポイントである ThreadStart ルーチンへのポインター。

[in, optional] StartContext

作成されたスレッドの実行が開始されたときに、 StartContext パラメーターとして ThreadStart ルーチンに渡されるコンテキストポインター。

戻り値

IoCreateSystemThread は、新しいスレッドが正常に作成された場合にSTATUS_SUCCESSを返します。可能な戻り値には、次のエラー状態コードが含まれます。

リターンコード	説明
STATUS_INVALID_HANDLE	ProcessHandle は有効なプロセスハンドルではありません。
STATUS_PROCESS_IS_TERMINATING	ProcessHandle で指定されたプロセスが終了しています。
STATUS_INSUFFICIENT_RESOURCES	要求された操作を実行するために使用できるシステムリソースが不足しています。

注釈

Windows 8以降、ドライバーは IoCreateSystemThread を呼び出して、デバイス専用スレッドを作成できます。このルーチンは、スレッド環境ブロック (TEB) またはユーザーモードコンテキストを持たない新しいシステムスレッドを作成し、カーネルモードでのみ実行します。

通常、ドライバーは、デバイスを起動するとき、またはドライバーのディスパッチXxx ルーチンが I/O 要求の受信を開始するときに IoCreateSystemThread を呼び出します。たとえば、ドライバーはこのルーチンを呼び出して、 ディスパッチXxx ルーチンが非同期デバイス制御要求を受け取ったときにスレッドを作成する場合があります。

ProcessHandle パラメーターが NULL の場合、作成されたスレッドはシステムプロセスに関連付けられます。このようなスレッドは、システムがシャットダウンされるか、スレッドが終了するまで実行を続けます。

システムプロセス以外のプロセスコンテキストで実行されるドライバールーチンは、IoCreateSystemThread の ObjectAttributes パラメーターのOBJ_KERNEL_HANDLE属性を設定する必要があります。この属性は、 IoCreateSystemThread によって返されるハンドルの使用を、カーネルモードで実行されているプロセスに制限します。それ以外の場合は、ドライバーが実行されているコンテキスト内のプロセスによってスレッドハンドルにアクセスできます。ドライバーは、次のコード例に示すように、 InitializeObjectAttributes マクロを呼び出して、オブジェクト属性のOBJ_KERNEL_HANDLE属性を設定できます。

OBJECT_ATTRIBUTES ObjectAttributes;

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

IoCreateSystemThread は PsCreateSystemThread ルーチンに似ていますが、呼び出し元のドライバーオブジェクトまたはデバイスオブジェクトへのポインターである追加のパラメーター IoObject があります。 IoCreateSystemThread では、このパラメーターを使用して、作成されたスレッドが存在する間、ドライバーがアンロードできないようにします。このスレッドで StartRoutine を実行するようにスケジュールする前に、 IoCreateSystemThread は IoObject オブジェクトへのカウントされた参照を受け取ります。 I/O マネージャーは、作成されたスレッドが終了した後、この参照を解放します。したがって、このオブジェクトは、作成されたスレッドの有効期間にわたって保持されます。

PsCreateSystemThread ルーチンによって作成されるシステムスレッドとは対照的に、IoCreateSystemThread によって作成されたスレッドは、PsTerminateSystemThread ルーチンを呼び出してそれ自体を終了しません。代わりに、I/O マネージャーは、スレッドの終了時に作成されたスレッドの代わりに PsTerminateSystemThread を呼び出します。

要件

要件	値
サポートされている最小のクライアント	Windows 8 以降で使用できます。
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL