IoCreateSystemThread 関数 (wdm.h)
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 |