ZwQueryDirectoryFile 関数 (ntifs.h)

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

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 によって返されるハンドル。呼び出し元が 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 の場合、 ZwQueryDirectoryFile は最初に見つかったエントリのみを返します。

[in, optional] FileName

FileHandle で指定されたディレクトリ内のファイルの名前 (またはワイルドカードが使用されている場合は複数のファイル) を含む、呼び出し元によって割り当てられた Unicode 文字列へのオプションのポインター。このパラメーターは省略可能です。

FileName が NULL でない場合は、FileName 文字列と一致する名前のファイルのみがディレクトリスキャンに含まれます。
FileName が NULL の場合、ReturnSingleEntry が FALSE の場合、すべてのファイルが含まれます。ReturnSingleEntry が TRUE の場合、1 つのファイルが含まれます。

FileName は検索式として使用され、特定のハンドルに対する ZwQueryDirectoryFile の最初の呼び出しでキャプチャされます。 ZwQueryDirectoryFile の後続の呼び出しでは、最初の呼び出しで設定された検索式が使用されます。後続の呼び出しに渡される FileName パラメーターは無視されます。

[in] RestartScan

ディレクトリ内の最初のエントリからスキャンを開始する場合は 、TRUE に設定します。前の呼び出しからスキャンを再開する場合は FALSE に 設定します。

特定のハンドルに対して ZwQueryDirectoryFile ルーチンが呼び出されると、 RestartScan パラメーターは、値に関係なく TRUE に設定されたかのように扱われます。後続の ZwQueryDirectoryFile 呼び出しでは、 RestartScan パラメーターの値が受け入れられます。

戻り値

ZwQueryDirectoryFile ルーチンは、STATUS_SUCCESSまたは適切なエラー状態を返します。返すことができるエラー状態値のセットは、ファイルシステム固有です。 ZwQueryDirectoryFile は、IoStatusBlock の Information メンバー内の指定された FileInformation バッファーに実際に書き込まれたバイト数も返します。考えられるエラーコードの一覧については、「 NtQueryDirectoryFileEx 」を参照してください。

注釈

ZwQueryDirectoryFile ルーチンは、FileHandle によって表されるディレクトリに含まれているファイルに関する情報を返します。

指定した場合、FileName は、特定の FileHandle に対する ZwQueryDirectoryFile に対する後続のすべての呼び出しのディレクトリスキャンに含まれるエントリを決定します。

一致するエントリが少なくとも 1 つある場合、 ZwQueryDirectoryFile はエントリごとに FILE_XXX_INFORMATION 構造体を作成し、バッファーに格納します。

少なくとも 1 つの一致するディレクトリエントリが見つかったと仮定すると、情報が返されるエントリの数は、次のうち最小になります。

ReturnSingleEntry が TRUE で FileName が NULL の場合、1 つのエントリ。
FileName が NULL でない場合に、FileName 文字列と一致するエントリの数。文字列にワイルドカードが含まれない場合は、一致するエントリが最大 1 つ存在する可能性があります。
指定したバッファーに収まる情報を持つエントリの数。
ディレクトリに含まれるエントリの数。

ZwQueryDirectoryFile の最初の呼び出しで、最初に見つかったエントリに対して作成される構造体が大きすぎて出力バッファーに収まらない場合、このルーチンは次の処理を行います。

構造体の固定部分を FileInformation の出力バッファーに書き込みます。固定部分は、最終的な FileName 文字列を除くすべてのフィールドで構成されます。最初の呼び出しでは、後続の呼び出しでは行われませんが、I/O システムは、適切な FILE_XXX_INFORMATION 構造体の固定部分を保持するのに十分な大きさのバッファーを確保します。
FileName 文字列と同じ量の出力バッファーに書き込みます。
STATUS_BUFFER_OVERFLOWなどの適切な状態値を返します。

呼び出しごとに、ZwQueryDirectoryFile は FileInformation が指すバッファーに完全に含めることができるのと同じ数のFILE_XXX_INFORMATION構造体 (ディレクトリエントリごとに 1 つ) を返します。

最初の呼び出しでは、 ZwQueryDirectoryFile は、出力バッファーに少なくとも 1 つの完全な構造体が含まれている場合にのみ、STATUS_SUCCESSを返します。
後続の呼び出しでは、出力バッファーに構造体が含まれない場合、ZwQueryDirectoryFile は STATUS_SUCCESSを返しますが、IoStatusBlock-Information> = 0 を設定して、呼び出し元にこの条件を通知します。この場合、呼び出し元はより大きなバッファーを割り当て、 ZwQueryDirectoryFile をもう一度呼び出す必要があります。残りのエントリに関する情報は報告されません。したがって、上記の 1 つのエントリのみが返される場合を除き、ディレクトリ全体の内容を列挙するには 、ZwQueryDirectoryFile を少なくとも 2 回呼び出す必要があります。

ZwQueryDirectoryFile を呼び出すときに、ZwQueryDirectoryFile 呼び出しと並行して発生するディレクトリに対する変更が表示される場合があります。この動作は、基になるファイルシステムの実装に依存します。

ZwQueryDirectoryFile の最後の呼び出しでは、空の出力バッファーが返され、STATUS_NO_MORE_FILESなどの適切な状態値が報告されます。

ZwQueryDirectoryFile が同じディレクトリで複数回呼び出され、他の操作でそのディレクトリの内容が変更された場合、操作のタイミングによっては、変更が表示される場合と表示されない場合があります。

ZwQueryDirectoryFile は、ファイルシステムでサポートされていない FILE_XXX_INFORMATION 構造体の任意のメンバーで 0 を返します。

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

その他のファイル情報クエリルーチンの詳細については、「ファイルオブジェクト」を参照してください。

注意

ZwQueryDirectoryFile 関数の呼び出しがユーザーモードで行われる場合は、"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 コンプライアンス規則	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)