次の方法で共有

NtQueryDirectoryFileEx 関数 (ntifs.h)

  • [アーティクル]

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

構文

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFileEx(
  [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,
                 FILE_INFORMATION_CLASS FileInformationClass,
  [in]           ULONG                  QueryFlags,
  [in, optional] PUNICODE_STRING        FileName
);

パラメーター

[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 に従ってこのパラメーターを設定する必要があります。

FileInformationClass

ディレクトリ内のファイルに関して返される情報の種類。 ディレクトリ内のファイルに関して返される情報の種類。 FileInformationClass には、次の FILE_INFORMATION_CLASS 値のいずれかを指定できます。

値 意味
FileDirectoryInformation (1) 各ファイルの FILE_DIRECTORY_INFORMATION 構造体を返します。
FileFullDirectoryInformation (2) 各ファイルの FILE_FULL_DIR_INFORMATION 構造体を返します。
FileBothDirectoryInformation (3) 各ファイルの FILE_BOTH_DIR_INFORMATION 構造体を返します。
FileNamesInformation (12) 各ファイルの FILE_NAMES_INFORMATION 構造体を返します。
FileObjectIdInformation (29) ボリュームにオブジェクト ID を持つ各ファイルの FILE_OBJECTID_INFORMATION 構造体を返します。 この情報クラスは、NTFS ボリューム上の特殊なディレクトリ "\$Extend\$ObjId:$O:$INDEX_ALLOCATION" に対してのみ有効です。
FileQuotaInformation (32) クォータが適用されているボリューム上の各ユーザーに対して、1 つの FILE_QUOTA_INFORMATION 構造を返します。 この情報クラスは、NTFS ボリューム上の特殊なディレクトリ "\$Extend\$Quota:$Q:$INDEX_ALLOCATION" に対してのみ有効です。
FileReparsePointInformation (33) ボリューム上に再解析ポイントがあるファイルごとに、1 つの FILE_REPARSE_POINT_INFORMATION 構造体を返します。 この情報クラスは、NTFS ボリュームと ReFS ボリュームの特殊なディレクトリ "\$Extend\$Reparse:$R:$INDEX_ALLOCATION" に対してのみ有効です。
FileIdBothDirectoryInformation (37) 各ファイルの FILE_ID_BOTH_DIR_INFORMATION 構造体を返します。
FileIdFullDirectoryInformation (38) 各ファイルの FILE_ID_FULL_DIR_INFORMATION 構造体を返します。
FileIdGlobalTxDirectoryInformation (50) 各ファイルの FILE_ID_GLOBAL_TX_DIR_INFORMATION 構造体を返します。
FileIdExtdDirectoryInformation (60) 各ファイルの FILE_ID_EXTD_DIR_INFORMATION 構造体を返します。
FileIdExtdBothDirectoryInformation (63) 各ファイルの FILE_ID_EXTD_BOTH_DIR_INFORMATION 構造体を返します。

[in] QueryFlags

SL_QUERY_DIRECTORY_MASKに含まれる 1 つ以上のフラグ。 次の表に、指定できる値を指定します。

値 意味
SL_RESTART_SCAN (0x00000001) スキャンは、ディレクトリ内の最初のエントリから開始されます。 このフラグが設定されていない場合、スキャンは最後のクエリが終了した場所から再開されます。
SL_RETURN_SINGLE_ENTRY (0x00000002) 通常、戻りバッファーには、適合する一致するディレクトリ エントリが含まれます。 このフラグが設定されている場合、ファイル システムは一度に 1 つのディレクトリ エントリのみを返します。 これにより、操作の効率が低下します。
SL_INDEX_SPECIFIED (0x00000004) スキャンは、ディレクトリ内の指定したインデックス位置から開始する必要があります。 このフラグは、独自のIRP_MJ_DIRECTORY_CONTROL IRP を生成する場合にのみ設定できます。インデックスは IRP で指定されます。 位置の指定方法は、ファイル システムによって異なります。
SL_RETURN_ON_DISK_ENTRIES_ONLY (0x00000008) ディレクトリ仮想化または Just-In-Time 拡張を実行するファイル システム フィルターは、要求をファイル システムに渡し、現在ディスク上にあるエントリを返すだけです。 すべてのファイル システムでこのフラグがサポートされているわけではありません。
SL_NO_CURSOR_UPDATE_QUERY (0x00000010) ファイル システムでは、FileObject ディレクトリごとのカーソル情報が保持されます。 複数のスレッドが同じ FileObject を使用してクエリを実行する場合、FileObject ごとの構造体へのアクセスは、カーソル状態の破損を防ぐためにシングル スレッドになります。 このフラグは、FileObject ごとのカーソル状態情報を更新しないようにファイル システムに指示するため、複数のスレッドが同じハンドルを使用して並列でクエリを実行できるようにします。 各呼び出しでSL_RESTART_SCANが指定されているかのように動作します。 次の呼び出しで野生のカード パターンが指定された場合、操作は最後のクエリが終了した場所を取得しません。 これにより、真の非同期ディレクトリ クエリのサポートが可能になります。 TxF トランザクション内でこのフラグを使用すると、操作は失敗します。 すべてのファイル システムでこのフラグがサポートされているわけではありません。

[in, optional] FileName

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

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

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

戻り値

NtQueryDirectoryFileEx は 、STATUS_SUCCESSまたは適切なエラー状態を返します。 返すことができるエラー状態値のセットは、ファイル システム固有です。 NtQueryDirectoryFileEx は、IoStatusBlock の Information メンバー内の指定された FileInformation バッファーに実際に書き込まれたバイト数も返します。 考えられるエラー コードと理由は次のとおりです。

リターン コード 意味
STATUS_BUFFER_OVERFLOW 出力バッファーは、完全なファイル名を返すには十分な大きさではありません。
STATUS_BUFFER_TOO_SMALL 出力バッファーは、 少なくとも FileInformationClass によって識別される基本構造には十分な大きさではありません。
STATUS_INVALID_INFO_CLASS 無効な FileInformationClass が指定されたか、情報クラスが特殊な条件に対してのみ有効です (たとえば、特殊なディレクトリに対してのみ有効)。
STATUS_INVALID_PARAMETER ファイル システムのパラメーターの 1 つが無効です。

注釈

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

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

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

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

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

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

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

各呼び出しで、NtQueryDirectoryFileEx は、FileInformation が指すバッファーに完全に格納できるFILE_XXX_INFORMATION 構造体 (ディレクトリ エントリごとに 1 つ) を返します。

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

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

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

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

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

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

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

注意

NtQueryDirectoryFileEx 関数の呼び出しがカーネル モードで発生する場合は、"NtQueryDirectoryFileEx" ではなく"ZwQueryDirectoryFileEx" という名前を使用する必要があります。

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

要件

要件 値
サポートされている最小のクライアント Windows 10 バージョン 1709
Header ntifs.h
Library NtosKrnl.lib
[DLL] NtosKrnl.exe
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