ZwQueryDirectoryFile 関数 (ntifs.h)
ZwQueryDirectoryFile ルーチンは、指定されたファイル ハンドルによって指定されたディレクトリ内のファイルに関するさまざまな情報を返します。
構文
NTSYSAPI NTSTATUS ZwQueryDirectoryFile(
[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
ZwCreateFile または ZwOpenFile によって返されるハンドルは、情報が要求されているディレクトリを表すファイル オブジェクトの。 呼び出し元が、
[in, optional] Event
呼び出し元によって作成されたイベントの省略可能なハンドル。 このパラメーターを指定すると、要求された操作が完了し、指定されたイベントが Signaled 状態に設定されるまで、呼び出し元は待機状態になります。 このパラメーターは省略可能であり、NULL
[in, optional] ApcRoutine
要求された操作が完了したときに呼び出される、呼び出し元が指定した省略可能な APC ルーチンのアドレス。 このパラメーターは省略可能であり、NULL
[in, optional] ApcContext
呼び出し元が APC を提供する場合、または I/O 完了オブジェクトがファイル オブジェクトに関連付けられている場合は、呼び出し元によって決定されたコンテキスト領域へのオプションのポインター。 操作が完了すると、このコンテキストが指定されている場合は APC に渡されるか、関連付けられている I/O 完了オブジェクトに I/O マネージャーが投稿する完了メッセージの一部として含まれます。
このパラメーターは省略可能であり、NULL
[out] IoStatusBlock
最終的な完了状態と操作に関する情報を受け取る IO_STATUS_BLOCK 構造体へのポインター。 データを返す呼び出しが成功した場合、構造体の Information メンバーで、FileInformation バッファーに書き込まれたバイト数が返されます。
[out] FileInformation
ファイルに関する必要な情報を受け取る出力バッファーへのポインター。 バッファーで返される情報の構造は、FileInformationClass パラメーターによって定義されます。
[in] Length
FileInformationが指すバッファーのサイズ (バイト単位)。 呼び出し元は、指定された FileInformationClassに従ってこのパラメーターを設定する必要があります。
[in] FileInformationClass
ディレクトリ内のファイルに関して返される情報の種類。 使用可能な値の一覧については、NtQueryDirectoryFileEx の FileInformationClass パラメーターを参照してください。
[in] ReturnSingleEntry
1 つのエントリのみを返す必要がある場合は TRUE を
[in, optional] FileName
FileHandle
FileName が NULLされていない場合、ディレクトリ スキャンには、 FileName 文字列と一致する名前のファイルのみが含まれます。FileName が NULL場合、returnSingleEntry が FALSE 場合、すべてのファイルが含まれます。ReturnSingleEntry が TRUE 場合、1 つのファイルが含まれます。
[in] RestartScan
スキャン ディレクトリ内の最初のエントリでスキャンを開始する場合は、TRUE に設定します。 前の呼び出しからスキャンを再開する場合は、FALSE を
戻り値
ZwQueryDirectoryFile ルーチンは、STATUS_SUCCESSまたは適切なエラー状態を返します。 返されるエラー状態値のセットは、ファイル システム固有です。
備考
ZwQueryDirectoryFile ルーチンは、FileHandleによって表されるディレクトリに含まれているファイルに関する情報を返します。
指定した場合、FileName
一致するエントリが 1 つ以上存在する場合、ZwQueryDirectoryFile
少なくとも 1 つの一致するディレクトリ エントリが見つかった場合、情報が返されるエントリの数は、次の 最小 です。
ReturnSingleEntry が TRUE、FileName が NULL 場合は、1 つのエントリ。 - FileName が NULL
でない場合、 FileName 文字列に一致するエントリ数。 文字列にワイルドカードが含まれている場合は、一致するエントリが最大 1 つ存在する可能性があります。 - 指定したバッファーに収まる情報を持つエントリの数。
- ディレクトリに含まれるエントリの数。
ZwQueryDirectoryFileを
- 構造体の固定部分を FileInformationの出力バッファー
書き込みます。 固定部分は、最後の FileName 文字列を除くすべてのフィールドで構成されます。 最初の呼び出しでは、後続の呼び出しでは行われませんが、I/O システムは、適切な FILE_XXX_INFORMATION 構造体の固定部分を保持するのに十分な大きさのバッファーを確保します。 - FileName 文字列の多くを出力バッファーに書き込みます。
- STATUS_BUFFER_OVERFLOWなどの適切な状態値を返します。
各呼び出しで、ZwQueryDirectoryFile は、FILE_XXX_INFORMATION 構造体 (ディレクトリ エントリごとに 1 つ) を返します。これは、FileInformationが指すバッファーに完全に含めることができます。
- 最初の呼び出しでは、ZwQueryDirectoryFile
は、出力バッファーに少なくとも 1 つの完全な構造体が含まれている場合にのみ、STATUS_SUCCESSを返します。 - 後続の呼び出しで、出力バッファーに構造体が含まれている場合、ZwQueryDirectoryFile はSTATUS_SUCCESSを返しますが、IoStatusBlock->Information = 0 に設定して、この条件を呼び出し元に通知します。 この場合、呼び出し元は、より大きなバッファーを割り当て、ZwQueryDirectoryFile 再度 呼び出す必要があります。 残りのエントリに関する情報は報告されません。 したがって、上記の 1 つのエントリのみが返される場合を除き、ZwQueryDirectoryFile
を少なくとも 2 回呼び出して、ディレクトリ全体の内容を列挙する必要があります。
ZwQueryDirectoryFile
ZwQueryDirectoryFile を
ZwQueryDirectoryFile が同じディレクトリで複数回呼び出され、他の操作でそのディレクトリの内容が変更された場合、操作のタイミングによっては、変更が表示される場合と表示されない場合があります。
ZwQueryDirectoryFile は、ファイル システムでサポートされていない FILE_XXX_INFORMATION 構造体のメンバーで 0 を返します。
ZwQueryDirectoryFile の呼び出し元は、IRQL = PASSIVE_LEVEL で実行され、特殊なカーネル API が有効になっている 必要があります。
その他のファイル情報照会ルーチンの詳細については、ファイル・オブジェクト
手記
ZwQueryDirectoryFile 関数の呼び出しがユーザー モードで発生する場合は、"ZwQueryDirectoryFile" ではなく"NtQueryDirectoryFile" という名前を使用する必要があります。
カーネル モード ドライバーからの呼び出しの場合、Windows ネイティブ システム サービス ルーチンの NtXxx および ZwXxx バージョンは、入力パラメーターを処理および解釈する方法で動作が異なる場合があります。 ルーチンの NtXxx と ZwXxx バージョンの間の関係の詳細については、「ネイティブ システム サービス ルーチンの Nt および Zw バージョンの使用 を参照してください。
必要条件
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント | Windows XP。 |
| ターゲット プラットフォーム の |
万国 |
| ヘッダー | ntifs.h (Ntifs.h を含む) |
| ライブラリ | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (「解説」セクションを参照) |
| DDI コンプライアンス規則 を |
HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |
関連項目
FILE_REPARSE_POINT_INFORMATION