NtQueryDirectoryFile 関数 (ntifs.h)
NtQueryDirectoryFile ルーチンは、指定されたファイル ハンドルによって指定されたディレクトリ内のファイルに関するさまざまな種類の情報を返します。
構文
__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[out] PVOID FileInformation,
[in] ULONG Length,
[in] FILE_INFORMATION_CLASS FileInformationClass,
[in] BOOLEAN ReturnSingleEntry,
[in, optional] PUNICODE_STRING FileName,
[in] BOOLEAN RestartScan
);
パラメーター
[in] FileHandle
情報が要求されているディレクトリを表すファイル オブジェクトの NtCreateFile または NtOpenFile によって返されるハンドル。 呼び出し元が Event または ApcRoutine に NULL 以外の値を指定している場合は、非同期 I/O 用にファイル オブジェクトが開かれている必要があります。
[in, optional] Event
呼び出し元によって作成されたイベントの省略可能なハンドル。 このパラメーターを指定すると、要求された操作が完了し、指定されたイベントが Signaled 状態に設定されるまで、呼び出し元は待機状態になります。 このパラメーターは省略可能であり、NULL にすることができます。 呼び出し元が FileHandle が Signaled 状態に設定されるのを待機する場合は NULL にする必要があります。
[in, optional] ApcRoutine
要求された操作が完了したときに呼び出される、呼び出し元から提供される省略可能な APC ルーチンのアドレス。 このパラメーターは省略可能であり、NULL にすることができます。 ファイル オブジェクトに関連付けられている I/O 入力候補オブジェクトがある場合、このパラメーターは NULL である必要があります。
[in, optional] ApcContext
呼び出し元が APC を提供する場合、または I/O 完了オブジェクトがファイル オブジェクトに関連付けられている場合は、呼び出し元によって決定されたコンテキスト領域へのオプションのポインター。 操作が完了すると、このコンテキストは APC に渡されます (指定された場合)、または I/O マネージャーが関連付けられた I/O 完了オブジェクトに投稿する完了メッセージの一部として含まれます。
このパラメーターは省略可能であり、NULL にすることができます。 ApcRoutine が NULL で、ファイル オブジェクトに関連付けられている I/O 完了オブジェクトがない場合は NULL にする必要があります。
[out] IoStatusBlock
最終的 な完了 状態と操作に関する情報を受け取るIO_STATUS_BLOCK構造体へのポインター。 データを返す呼び出しが成功すると、 FileInformation バッファーに書き込まれたバイト数が構造体の Information メンバーに返されます。
[out] FileInformation
ファイルに関する必要な情報を受け取るバッファーへのポインター。 バッファーで返される情報の構造は、 FileInformationClass パラメーターによって定義されます。
[in] Length
FileInformation が指すバッファーのサイズ (バイト単位)。 呼び出し元は、指定された FileInformationClass に従ってこのパラメーターを設定する必要があります。
[in] FileInformationClass
ディレクトリ内のファイルに関して返される情報の種類。 ディレクトリ内のファイルに関して返される情報の種類。 使用可能な値の一覧については、NtQueryDirectoryFileEx の FileInformationClass パラメーターを参照してください。
[in] ReturnSingleEntry
1 つのエントリのみを返す場合は TRUE 、それ以外の場合は FALSE に設定します。 このパラメーターが TRUE の場合、 NtQueryDirectoryFile は最初に見つかったエントリのみを返します。
[in, optional] FileName
FileHandle で指定されたディレクトリ内のファイルの名前 (またはワイルドカードが使用されている場合は複数のファイル) を含む呼び出し元によって割り当てられた Unicode 文字列への省略可能なポインター。 このパラメーターは省略可能であり、NULL にすることができます。
FileName が NULL でない場合は、FileName 文字列と一致する名前を持つファイルのみがディレクトリ スキャンに含まれます。 FileName が NULL の場合、すべてのファイルが含まれます。
FileName は検索式として使用され、特定のハンドルに対する NtQueryDirectoryFile の最初の呼び出しでキャプチャされます。 NtQueryDirectoryFile の後続の呼び出しでは、最初の呼び出しで設定された検索式が使用されます。 後続の呼び出しに渡される FileName パラメーターは無視されます。
[in] RestartScan
スキャンがディレクトリ内の最初のエントリから開始する場合は TRUE に設定します。 前の呼び出しからスキャンを再開する場合は FALSE に 設定します。
特定のハンドルに対して NtQueryDirectoryFile ルーチンが呼び出されると、 RestartScan パラメーターは、 値に関係なく TRUE に設定されたかのように扱われます。 以降 の NtQueryDirectoryFile 呼び出しでは、 RestartScan パラメーターの値が受け入れられます。
戻り値
NtQueryDirectoryFileルーチンは、STATUS_SUCCESSまたは適切なエラー状態を返します。 返すことができるエラー状態値のセットは、ファイル システム固有です。 NtQueryDirectoryFileは、IoStatusblock の Information メンバー内の指定された FileInformation バッファーに実際に書き込まれたバイト数も返します。 考えられるエラー コードの一覧については、「 NtQueryDirectoryFileEx 」を参照してください。
注釈
NtQueryDirectoryFile ルーチンは、FileHandle で表されるディレクトリに含まれるファイルに関する情報を返します。
指定した場合、FileName パラメーターの値によって、指定された FileHandle に対する NtQueryDirectoryFile への後続のすべての呼び出しのディレクトリ スキャンに含まれるエントリが決定されます。
一致するエントリが少なくとも 1 つある場合、 NtQueryDirectoryFile はエントリごとに FILE_XXX_INFORMATION 構造体を作成し、バッファーに格納します。
少なくとも 1 つの一致するディレクトリ エントリが見つかった場合、情報が返されるエントリの数は、次のうち最小 です。
- ReturnSingleEntry が TRUE で FileName が NULL の場合、1 つのエントリ。
- FileName が NULL でない場合、FileName 文字列と一致するエントリの数。 (文字列にワイルドカードが含まれない場合は、一致するエントリが最大 1 つ存在する可能性があることに注意してください)。
- 指定したバッファーに情報が収まるエントリの数。
- ディレクトリに含まれるエントリの数。
NtQueryDirectoryFile の最初の呼び出しで、最初に見つかったエントリに対して作成された構造体が大きすぎて出力バッファーに収まらない場合、ルーチンは構造体の固定部分を出力バッファーに書き込みます。 その後、ルーチンは、 FileName 文字列の収まる量だけ出力バッファーに書き込みます。 (構造体の固定部分は、最終的な FileName 文字列を除くすべてのフィールドで構成されます。最初の呼び出しでは、後続の呼び出しでは行われませんが、I/O システムは、適切な FILE_XXX_INFORMATION 構造体の固定部分を保持するのに十分な大きさのバッファーを確保します。この場合、 NtQueryDirectoryFile は、STATUS_BUFFER_OVERFLOWなどの適切な状態値を返します。
NtQueryDirectoryFile は、呼び出しごとに、FileInformation が指すバッファーに完全に含めることができるのと同じ数のFILE_XXX_INFORMATION構造体 (ディレクトリ エントリごとに 1 つ) を返します。 最初の呼び出しでは、出力バッファーに少なくとも 1 つの完全な構造体が含まれている場合にのみ、 NtQueryDirectoryFile はSTATUS_SUCCESSを返します。 後続の呼び出しでは、出力バッファーに構造体が含まれない場合、NtQueryDirectoryFile は STATUS_SUCCESSを返しますが、IoStatusblock-Information> = 0 を設定して、呼び出し元にこの条件を通知します。 この場合、呼び出し元は、より大きなバッファーを割り当てて 、NtQueryDirectoryFile をもう一度呼び出す必要があります。 残りのエントリに関する情報は報告されません。 したがって、上記の 1 つのエントリのみが返される場合を除き、 NtQueryDirectoryFile を少なくとも 2 回呼び出してディレクトリ全体の内容を列挙する必要があります。
NtQueryDirectoryFile を呼び出すと、NtQueryDirectoryFile 呼び出しと並行してディレクトリに加えられた変更が表示されることがあります。 この動作は、基になるファイル システムの実装に依存します。
NtQueryDirectoryFile の最後の呼び出しでは、空の出力バッファーが返され、STATUS_NO_MORE_FILESなどの適切な状態値が報告されます。
NtQueryDirectoryFile が同じディレクトリで複数回呼び出され、他の操作によってそのディレクトリの内容が変更された場合、操作のタイミングに応じて変更が表示される場合と表示されない場合があります。
NtQueryDirectoryFileは、ファイル システムでサポートされていない FILE_XXX_INFORMATION 構造体のメンバーに 0 を返します。
NtQueryDirectoryFile の呼び出し元は、IRQL = PASSIVE_LEVEL で実行され、特殊なカーネル APC が有効になっている必要があります。
その他のファイル情報クエリ ルーチンの詳細については、「 ファイル オブジェクト」を参照してください。
注意
NtQueryDirectoryFile 関数の呼び出しがユーザー モードで行われる場合は、"ZwQueryDirectoryFile" ではなく"NtQueryDirectoryFile" という名前を使用する必要があります。
カーネル モード ドライバーからの呼び出しの場合、Windows ネイティブ システム サービス ルーチンの NtXXX および ZwXXX バージョンは、入力パラメーターを処理および解釈する方法で動作が異なります。 ルーチンの NtXXX バージョンと ZwXXX バージョン間の関係の詳細については、「ネイティブ システム サービス ルーチンの Nt バージョンと Zw バージョンの使用」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP |
| 対象プラットフォーム | ユニバーサル |
| Header | ntifs.h (Ntifs.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (「解説」セクションを参照) |
| DDI コンプライアンス規則 | HwStorPortProhibitedDIs、PowerIrpDDis |