次の方法で共有

ZwQueryDirectoryFileEx 関数 (ntifs.h)

  • [アーティクル]

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 によって返されるハンドルは、情報が要求されているディレクトリを表すファイル オブジェクトの。 呼び出し元が イベント または ApcRoutineNULL 以外の値を指定する場合は、非同期 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 構造体へのポインター。 データを返す呼び出しが成功した場合、構造体の Information メンバーで、FileInformation バッファーに書き込まれたバイト数が返されます。

[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 の場合:
    • QueryFlagsでSL_RETURN_SINGLE_ENTRYが設定されていない場合は、すべてのファイルが含まれます。
    • 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 つの一致するディレクトリ エントリが見つかった場合、情報が返されるエントリの数は、次の 最小 です。

  • QueryFlags でSL_RETURN_SINGLE_ENTRYが設定され、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 で実行され、特殊なカーネル API が有効になっている 必要があります。

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

手記

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

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

必要条件

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

関連項目

FILE_BOTH_DIR_INFORMATION

FILE_DIRECTORY_INFORMATION

FILE_FULL_DIR_INFORMATION

FILE_ID_BOTH_DIR_INFORMATION

FILE_ID_FULL_DIR_INFORMATION

FILE_NAMES_INFORMATION

FILE_OBJECTID_INFORMATION

FILE_REPARSE_POINT_INFORMATION

UNICODE_STRING

ネイティブ システム サービス ルーチンの Nt バージョンと Zw バージョンを使用した

ZwCreateFile

ZwOpenFile