ZwQueryDirectoryFileEx 関数 (ntifs.h)

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

ZwQueryDirectoryFileEx ルーチンは、指定されたファイルハンドルによって指定されたディレクトリ内のファイルに関するさまざまな情報を返します。

構文

NTSYSAPI NTSTATUS ZwQueryDirectoryFileEx(
  [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]           ULONG                  QueryFlags,
  [in, optional] PUNICODE_STRING        FileName
);

パラメーター

[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] QueryFlags

SL_QUERY_DIRECTORY_MASKに含まれる 1 つ以上のフラグ。使用可能な値の一覧については、NtQueryDirectoryFileEx の QueryFlags パラメーターを参照してください。

[in, optional] FileName

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

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

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

戻り値

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

注釈

ZwQueryDirectoryFileEx は、 FileHandle で表されるディレクトリに含まれているファイルに関する情報を返します。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

注意

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

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

要件

要件	値
サポートされている最小のクライアント	Windows 10 バージョン 1709
Header	ntifs.h
IRQL	PASSIVE_LEVEL (「解説」セクションを参照)