NtQueryDirectoryFile 関数 (ntifs.h)

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

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

構文

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFile(
  [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

情報が要求されているディレクトリを表すファイルオブジェクトの 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 に従ってこのパラメーターを設定する必要があります。

[in] FileInformationClass

ディレクトリ内のファイルに関して返される情報の種類。ディレクトリ内のファイルに関して返される情報の種類。使用可能な値の一覧については、NtQueryDirectoryFileEx の FileInformationClass パラメーターを参照してください。

[in] ReturnSingleEntry

1 つのエントリのみを返す場合は TRUE 、それ以外の場合は FALSE に設定します。このパラメーターが TRUE の場合、 NtQueryDirectoryFile は最初に見つかったエントリのみを返します。

[in, optional] FileName

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

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

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

[in] RestartScan

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

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

戻り値

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

注釈

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

指定した場合、FileName パラメーターの値によって、指定された FileHandle に対する NtQueryDirectoryFile への後続のすべての呼び出しのディレクトリスキャンに含まれるエントリが決定されます。

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

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

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

NtQueryDirectoryFile の最初の呼び出しで、最初に見つかったエントリに対して作成された構造体が大きすぎて出力バッファーに収まらない場合、ルーチンは構造体の固定部分を出力バッファーに書き込みます。その後、ルーチンは、 FileName 文字列の収まる量だけ出力バッファーに書き込みます。 (構造体の固定部分は、最終的な FileName 文字列を除くすべてのフィールドで構成されます。最初の呼び出しでは、後続の呼び出しでは行われませんが、I/O システムは、適切な FILE_XXX_INFORMATION 構造体の固定部分を保持するのに十分な大きさのバッファーを確保します。この場合、 NtQueryDirectoryFile は、STATUS_BUFFER_OVERFLOWなどの適切な状態値を返します。

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

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

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

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

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

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

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

注意

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