ZwQueryInformationFile 関数 (wdm.h)

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

ZwQueryInformationFile ルーチンは、ファイルオブジェクトに関するさまざまな種類の情報を返します。

構文

NTSYSAPI NTSTATUS ZwQueryInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [out] PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

パラメーター

[in] FileHandle

ファイルオブジェクトへのハンドル。ハンドルは、 ZwCreateFile または ZwOpenFile の正常な呼び出しによって作成 されます。

[out] IoStatusBlock

最終的 な完了 状態と操作に関する情報を受け取るIO_STATUS_BLOCK構造体へのポインター。 Information メンバーは、このルーチンが FileInformation バッファーに実際に書き込むバイト数を受け取ります。

[out] FileInformation

ルーチンがファイルオブジェクトに関する要求された情報を書き込む呼び出し元によって割り当てられたバッファーへのポインター。 FileInformationClass パラメーターは、呼び出し元が要求する情報の種類を指定します。

[in] Length

FileInformation が指すバッファーのサイズ (バイト単位)。

[in] FileInformationClass

FileInformation が指すバッファー内で、ファイルに関して返される情報の種類を指定します。デバイスドライバーと中間ドライバーは、次の FILE_INFORMATION_CLASS 値のいずれかを指定できます。

FILE_INFORMATION_CLASS値	返される情報の種類
FileBasicInformation (4)	FILE_BASIC_INFORMATION構造体。呼び出し元は、 DesiredAccess パラメーターで指定されたFILE_READ_ATTRIBUTES フラグを使用してファイルを開いている必要があります。
FileStandardInformation (5)	FILE_STANDARD_INFORMATION構造体。呼び出し元は、 DesiredAccess の特定の要件なしで、ファイルが開いている限り、この情報に対してクエリを実行できます。
FileInternalInformation (6)	FILE_INTERNAL_INFORMATION構造体。この構造体は、NTFS 内のファイルを一意に識別する 64 ビットのファイル ID を指定します。他のファイルシステムでは、このファイル ID は一意であるとは限りません。
FileEaInformation (7)	FILE_EA_INFORMATION構造体。この構造体は、ファイルに関連付けられている拡張属性ブロックのサイズを指定します。
FileAccessInformation (8)	FILE_ACCESS_INFORMATION構造体。この構造体には、アクセスマスクが含まれています。アクセスマスクの詳細については、「 ACCESS_MASK」を参照してください。
FileNameInformation (9)	FILE_NAME_INFORMATION構造体。構造体には、ファイルの完全パスまたはその一部のみを含めることができます。呼び出し元は、 DesiredAccess の特定の要件なしで、ファイルが開いている限り、この情報に対してクエリを実行できます。ファイル名の構文の詳細については、このトピックで後述する「解説」セクションを参照してください。
FilePositionInformation (14)	FILE_POSITION_INFORMATION構造体。呼び出し元は、DesiredAccess パラメーターで指定された DesiredAccess FILE_READ_DATAフラグまたはFILE_WRITE_DATA フラグ、および CreateOptions パラメーターで指定されたFILE_SYNCHRONOUS_IO_ALERTまたはFILE_SYNCHRONOUS_IO_NONALERT フラグを使用して、ファイルを開いている必要があります。
FileModeInformation (16)	FILE_MODE_INFORMATION構造体。この構造体には、ファイルにアクセスできるモードを指定するフラグのセットが含まれています。これらのフラグは、IoCreateFile ルーチンの CreateOptions パラメーターで指定できるオプションのサブセットです。
FileAlignmentInformation (17)	FILE_ALIGNMENT_INFORMATION構造体。呼び出し元は、 DesiredAccess[ の特定の要件なしで、ファイルが開いている限り、この情報に対してクエリを実行できます。この情報は、 CreateOptions** パラメーターで指定されたFILE_NO_INTERMEDIATE_BUFFERING フラグを使用してファイルを開いた場合に便利です。
FileAllInformation (18)	FILE_ALL_INFORMATION構造体。複数のファイル情報構造体を 1 つの構造体に組み合わせることで、 FILE_ALL_INFORMATION ファイルに関する情報を取得するために必要なクエリの数を減らすことができます。
FileNetworkOpenInformation (34)	FILE_NETWORK_OPEN_INFORMATION構造体。呼び出し元は、 DesiredAccess パラメーターで指定されたFILE_READ_ATTRIBUTES フラグを使用してファイルを開いている必要があります。
FileAttributeTagInformation (35)	FILE_ATTRIBUTE_TAG_INFORMATION構造体。呼び出し元は、 DesiredAccess パラメーターで指定されたFILE_READ_ATTRIBUTES フラグを使用してファイルを開いている必要があります。
FileIoPriorityHintInformation (43)	FILE_IO_PRIORITY_HINT_INFORMATION構造体。呼び出し元は、DesiredAccess パラメーターで指定されたFILE_READ_DATA フラグを使用してファイルを開いている必要があります。
FileIsRemoteDeviceInformation (51)	FILE_IS_REMOTE_DEVICE_INFORMATION構造体。呼び出し元は、 DesiredAccess の特定の要件なしで、ファイルが開いている限り、この情報に対してクエリを実行できます。
FileKnownFolderInformation (76)	FILE_KNOWN_FOLDER_INFORMATION構造体。 Windows Server 2022 以降で使用できます。

戻り値

ZwQueryInformationFile は 、STATUS_SUCCESSまたは適切な NTSTATUS エラーコードを返します。

注釈

ZwQueryInformationFile は 、指定されたファイルオブジェクトに関する情報を返します。特定のデバイスまたはファイルシステムでサポートされていない FILE_XXX_INFORMATION 構造体のメンバーでは 0 が返されることに注意してください。

FileInformationClass = FileNameInformation の場合、ファイル名はFILE_NAME_INFORMATION構造体で返されます。ファイル名の正確な構文は、いくつかの要因によって異なります。

ZwCreateFile に完全なパスを送信してファイルを開いた場合、ZwQueryInformationFile はその完全パスを返します。
ObjectAttributes-RootDirectory> ハンドルが ZwCreateFile の呼び出しで名前で開かれた後、このルートディレクトリハンドルに対して ZwCreateFile によってファイルが開かれた場合、ZwQueryInformationFile は完全なパスを返します。
ObjectAttributes-RootDirectory> ハンドルが ZwCreateFile の呼び出しで (FILE_OPEN_BY_FILE_ID フラグを使用して) ファイル ID によって開かれた後、このルートディレクトリハンドルに対して ZwCreateFile によってファイルが開かれた場合、ZwQueryInformationFile は相対パスを返します。
ただし、ユーザーが SeChangeNotifyPrivilege を持っている場合、 ZwQueryInformationFile はすべてのケースで完全なパスを返します。
相対パスのみが返される場合、ファイル名の文字列は円記号で始まりません。
完全なパスとファイル名が返された場合、文字列は場所に関係なく、1 つの円記号で始まります。したがって、ファイル C:\dir1\dir2\filename.ext は \dir1\dir2\filename.ext として表示され、ファイル \server\share\dir1\dir2\filename.ext は \server\share\dir1\dir2\filename.ext として表示されます。

バッファーオーバーフローが原因で ZwQueryInformationFile が失敗した場合、FileNameInformation を実装するドライバーは、バッファーに収まるファイル名の WCHAR 文字の数を返し、FILE_NAME_INFORMATION構造体の FileNameLength パラメーターに必要な完全な長さを指定する必要があります。完全なファイル名を取得できるように、ファイル名の長さを使用してクエリを再発行する必要があります。このパターンに従わないドライバーでは、完全なファイル名を取得するまで、徐々に長さが増える必要があります。ファイルの操作の詳細については、「ドライバーでのファイルの使用」を参照してください。

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

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

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

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (「解説」セクションを参照)
DDI コンプライアンス規則	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)