NtQueryInformationFile 関数 (ntifs.h)

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

NtQueryInformationFile ルーチンは、ファイルオブジェクトに関するさまざまな種類の情報を返します。いくつかのファイル情報クラスでより効率的に使用できる NtQueryInformationByName も参照してください。

構文

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [out] PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

パラメーター

[in] FileHandle

ファイルオブジェクトへのハンドル。ハンドルは、 NtCreateFile または NtOpenFile を正常に呼び出すか、同等のファイル作成または開くルーチンを呼び出すことによって作成されます。

[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 ファイルに関する情報を取得するために必要なクエリの数を減らすことができます。
FileAlternateNameInformation (21)	ファイルの代替名情報 (その 8.3 形式名) を返す FILE_ALL_INFORMATION 構造体。
FileStreamInformation (22)	ファイルまたはディレクトリのデータストリームを列挙する FILE_STREAM_INFORMATION 構造体のバッファー。
FileCompressionInformation (28)	ファイルの圧縮情報を返す FILE_COMPRESSION_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 フラグを使用してファイルを開いている必要があります。
FileSfioReserveInformation (44)	FILE_SFIO_RESERVE_INFORMATION構造体。
FileHardLinkInformation (46)	FILE_LINKS_INFORMATION構造体。
FileNormalizedNameInformation (48)	ファイルの正規化された名前を返す FILE_NAME_INFORMATION 構造体。
FileIsRemoteDeviceInformation (51)	FILE_IS_REMOTE_DEVICE_INFORMATION構造体。呼び出し元は、 DesiredAccess の特定の要件なしで、ファイルが開いている限り、この情報に対してクエリを実行できます。
FileStandardLinkInformation (54)	FILE_STANDARD_LINK_INFORMATION構造体。
FileIdInformation (59)	FILE_ID_INFORMATION構造体。
FileDesiredStorageClassInformation (67)	FILE_DESIRED_STORAGE_CLASS_INFORMATION構造体。
FileStatInformation (68)	FILE_STAT_INFORMATION
FileStatLxInformation (70)	FILE_STAT_LX_INFORMATION
FileCaseSensitiveInformation (71)	FILE_CASE_SENSITIVE_INFORMATION構造体。呼び出し元は、 DesiredAccess パラメーターで指定されたFILE_READ_ATTRIBUTES フラグを使用してファイルを開いている必要があります。この値は、バージョン 1803 Windows 10 以降で使用できます。
FileStorageReserveIdInformation (74)	FILE_STORAGE_RESERVE_ID_INFORMATION構造体。
FileCaseSensitiveInformationForceAccessCheck (75)	FILE_CASE_SENSITIVE_INFORMATION構造体。呼び出し元は、 DesiredAccess パラメーターで指定されたFILE_READ_ATTRIBUTES フラグを使用してファイルを開いている必要があります。これは、ユーザーモードの呼び出し元に適用されるチェックと同様に、IOManager がカーネルモードドライバーのアクセスチェックを強制的に実行するために使用される FileCaseSensitiveInformation 操作の特別なバージョンです。この操作は IOManager によってのみ認識され、ファイルシステムはそれを受信しないでください。この値は、バージョン 1803 Windows 10 以降で使用できます。
FileKnownFolderInformation (76)	FILE_KNOWN_FOLDER_INFORMATION構造体。 Windows Server 2022 以降で使用できます。

戻り値

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

注釈

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

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

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

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

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

注意

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

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

要件

要件	値
サポートされている最小のクライアント	Windows 2000。
対象プラットフォーム	ユニバーサル
Header	ntifs.h (Wdm.h、Ntddk.h、Ntifs.h を含みます)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (「解説」セクションを参照)
DDI コンプライアンス規則	HwStorPortProhibitedDDIs、PowerIrpDDis