NtFsControlFile 関数 (ntifs.h)

[アーティクル]
07/11/2023

NtFsControlFile ルーチンは、指定したファイルシステムまたはファイルシステムフィルタードライバーにコントロールコードを直接送信し、対応するドライバーが指定したアクションを実行します。

構文

__kernel_entry NTSYSCALLAPI NTSTATUS NtFsControlFile(
  [in]            HANDLE           FileHandle,
  [in, optional]  HANDLE           Event,
  [in, optional]  PIO_APC_ROUTINE  ApcRoutine,
  [in, optional]  PVOID            ApcContext,
  [out]           PIO_STATUS_BLOCK IoStatusBlock,
  [in]            ULONG            FsControlCode,
  [in, optional]  PVOID            InputBuffer,
  [in]            ULONG            InputBufferLength,
  [out, optional] PVOID            OutputBuffer,
  [in]            ULONG            OutputBufferLength
);

パラメーター

[in] FileHandle

指定したアクションを実行するファイルまたはディレクトリを表すファイルオブジェクトの NtCreateFile または NtOpenFile によって返されるハンドル。呼び出し元が Event、ApcRoutine、APC コンテキスト (ApcContext の場合)、または完了コンテキスト (ApcContext 内) を指定する場合は、非同期 I/O 用にファイルオブジェクトが開かれている必要があります。

[in, optional] Event

呼び出し元によって作成されたイベントのハンドル。このパラメーターを指定すると、要求された操作が完了し、指定されたイベントが Signaled 状態に設定されるまで、呼び出し元は待機状態になります。このパラメーターは省略可能であり、NULL にすることができます。呼び出し元が FileHandle が Signaled 状態に設定されるのを待機する場合は、NULL である必要があります。

[in, optional] ApcRoutine

要求された操作が完了したときに呼び出される呼び出し元から提供された APC ルーチンのアドレス。このパラメーターは省略可能であり、NULL にすることができます。ファイルオブジェクトに関連付けられている I/O 完了オブジェクトがある場合は NULL である必要があります。

[in, optional] ApcContext

呼び出し元によって決定されたコンテキスト領域へのポインター。このパラメーター値は、呼び出し元が APC を提供する場合は APC コンテキストとして使用され、I/O 完了オブジェクトがファイルオブジェクトに関連付けられている場合は完了コンテキストとして使用されます。操作が完了すると、APC コンテキストが指定されている場合は APC に渡されるか、I/O マネージャーが関連付けられている I/O 完了オブジェクトに投稿する完了メッセージの一部として完了コンテキストが含まれます。

このパラメーターは省略可能であり、NULL にすることができます。 ApcRoutine が NULL で、ファイルオブジェクトに関連付けられている I/O 完了オブジェクトがない場合は、NULL にする必要があります。

[out] IoStatusBlock

最終的な完了状態と操作に関する情報を受け取るIO_STATUS_BLOCK構造体へのポインター。データを返す呼び出しが成功した場合、 OutputBuffer に書き込まれたバイト数は、この構造体の Information メンバーに返されます。

[in] FsControlCode

FSCTL_実行するファイルシステム制御操作を示すXXX コード。このパラメーターの値は、 InputBuffer と OutputBuffer の形式と必要な長さ、および次のパラメーターペアのうちどれが必要かを決定します。システム定義のFSCTL_XXX コードの詳細については、 DeviceIoControl のリファレンスエントリの「解説」セクションを参照してください。

[in, optional] InputBuffer

ターゲットドライバーに渡されるデバイス固有の情報を含む、呼び出し元によって割り当てられた入力バッファーへのポインター。 FsControlCode で入力データを必要としない操作が指定されている場合、このポインターは省略可能であり、NULL にすることができます。

[in] InputBufferLength

InputBuffer のバッファーのサイズ (バイト単位)。 InputBuffer が NULL の場合、この値は無視されます。

[out, optional] OutputBuffer

ターゲットドライバーから情報が返される、呼び出し元によって割り当てられた出力バッファーへのポインター。 FsControlCode で出力データを生成しない操作が指定されている場合、このポインターは省略可能であり、NULL にすることができます。

[in] OutputBufferLength

OutputBuffer のバッファーのサイズ (バイト単位)。 OutputBuffer が NULL の場合、この値は無視されます。

戻り値

NtFsControlFile は 、次のいずれかのSTATUS_SUCCESSまたは適切な NTSTATUS 値を返します。

注釈

NtFsControlFile は、システムとカーネルモードドライバーに対する入力データと出力データの一貫性のあるビューを提供しながら、通信インターフェイスを指定するドライバーに依存するメソッドをアプリケーションと基になるドライバーに提供します。

呼び出し元が非同期 I/O 用にファイルを開いた場合 (FILE_SYNCHRONOUS_XXX create/open オプションが設定されていません)、指定されたイベントがある場合は、デバイス制御操作の完了時にシグナル状態に設定されます。それ以外の場合、 FileHandle で指定されたファイルオブジェクトはシグナル状態に設定されます。 ApcRoutine が指定された場合は、ApcContext ポインターと IoStatusBlock ポインターを使用して呼び出されます。

カーネルモードドライバーに関して文書化されている FSCTL コードの一部を次に示します。

システム定義のFSCTL_XXX コードの詳細については、 DeviceIoControl のリファレンスエントリの「解説」セクションを参照してください。

システム定義IOCTL_XXX コードの詳細、およびドライバー固有のIOCTL_XXX 値または FSCTL_XXX 値の定義については、「 I/O 制御コードとデバイス入出力制御コードの使用」を参照してください。

ミニフィルターでは、 NtFsControlFile の代わりに FltFsControlFile を使用する必要があります。

NtFsControlFile の呼び出し元は、IRQL = PASSIVE_LEVELで実行され、特殊なカーネル APCs が有効になっている必要があります**。

NtFsControlFile 関数の呼び出しがユーザーモードで行われる場合は、"ZwFsControlFile" ではなく "NtFsControlFile" という名前を使用する必要があります。

カーネルモードドライバーからの呼び出しの場合、Windows ネイティブシステムサービスルーチンの NtXXX バージョンと ZwXXX バージョンは、入力パラメーターを処理および解釈する方法で動作が異なる場合があります。 ルーチンの NtXXX バージョンと ZwXXX バージョン間の関係の詳細については、「ネイティブシステムサービスルーチンの Nt バージョンと Zw バージョンの使用」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows 2000
対象プラットフォーム	ユニバーサル
Header	ntifs.h (Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (「解説」セクションを参照)
DDI コンプライアンス規則	HwStorPortProhibitedDDIs、PowerIrpDDis