Función NtQueryInformationFile (ntifs.h)

Artículo
07/11/2023

La rutina NtQueryInformationFile devuelve varios tipos de información sobre un objeto de archivo. Consulte también NtQueryInformationByName, que se puede usar de forma más eficaz para algunas clases de información de archivos.

Sintaxis

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

Parámetros

[in] FileHandle

Identificador de un objeto de archivo. El identificador se crea mediante una llamada correcta a NtCreateFile o NtOpenFile, o a una rutina de creación o apertura de un archivo equivalente.

[out] IoStatusBlock

Puntero a una estructura de IO_STATUS_BLOCK que recibe el estado de finalización final e información sobre la operación. El miembro Information recibe el número de bytes que esta rutina escribe realmente en el búfer FileInformation .

[out] FileInformation

Puntero a un búfer asignado por el autor de la llamada en el que la rutina escribe la información solicitada sobre el objeto de archivo. El parámetro FileInformationClass especifica el tipo de información que solicita el autor de la llamada.

[in] Length

Tamaño, en bytes, del búfer al que apunta FileInformation.

[in] FileInformationClass

Especifica el tipo de información que se va a devolver sobre el archivo, en el búfer al que apunta FileInformation . Los controladores intermedios y de dispositivo pueden especificar cualquiera de los siguientes valores de FILE_INFORMATION_CLASS (enumerados de menor a mayor valor de enumeración):

FILE_INFORMATION_CLASS valor	Tipo de información devuelta
FileBasicInformation (4)	Estructura FILE_BASIC_INFORMATION . El autor de la llamada debe haber abierto el archivo con la marca FILE_READ_ATTRIBUTES especificada en el parámetro DesiredAccess .
FileStandardInformation (5)	Estructura FILE_STANDARD_INFORMATION . El autor de la llamada puede consultar esta información siempre que el archivo esté abierto, sin requisitos concretos para DesiredAccess.
FileInternalInformation (6)	Estructura FILE_INTERNAL_INFORMATION . Esta estructura especifica un identificador de archivo de 64 bits que identifica de forma única un archivo en NTFS. En otros sistemas de archivos, no se garantiza que este identificador de archivo sea único.
FileEaInformation (7)	Estructura de FILE_EA_INFORMATION . Esta estructura especifica el tamaño del bloque de atributos extendidos asociado al archivo.
FileAccessInformation (8)	Estructura de FILE_ACCESS_INFORMATION . Esta estructura contiene una máscara de acceso. Para obtener más información sobre las máscaras de acceso, consulte ACCESS_MASK.
FileNameInformation (9)	Estructura FILE_NAME_INFORMATION . La estructura puede contener la ruta de acceso completa del archivo o solo una parte de él. El autor de la llamada puede consultar esta información siempre que el archivo esté abierto, sin requisitos concretos para DesiredAccess. Para obtener más información sobre la sintaxis de nombre de archivo, vea la sección Comentarios más adelante en este tema.
FilePositionInformation (14)	Estructura FILE_POSITION_INFORMATION . El autor de la llamada debe haber abierto el archivo con la marca DesiredAccess FILE_READ_DATA o FILE_WRITE_DATA especificada en el parámetro DesiredAccess y con la marca FILE_SYNCHRONOUS_IO_ALERT o FILE_SYNCHRONOUS_IO_NONALERT especificada en el parámetro CreateOptions .
FileModeInformation (16)	Estructura FILE_MODE_INFORMATION . Esta estructura contiene un conjunto de marcas que especifican el modo en el que se puede acceder al archivo. Estas marcas son un subconjunto de las opciones que se pueden especificar en el parámetro CreateOptions de la rutina IoCreateFile .
FileAlignmentInformation (17)	Estructura FILE_ALIGNMENT_INFORMATION . El autor de la llamada puede consultar esta información siempre que el archivo esté abierto, sin requisitos concretos para DesiredAccess. Esta información es útil si el archivo se abrió con la marca FILE_NO_INTERMEDIATE_BUFFERING especificada en el parámetro CreateOptions .
FileAllInformation (18)	Estructura de FILE_ALL_INFORMATION . Al combinar varias estructuras de información de archivos en una sola estructura, FILE_ALL_INFORMATION reduce el número de consultas necesarias para obtener información sobre un archivo.
FileAlternateNameInformation (21)	Estructura FILE_ALL_INFORMATION en la que se va a devolver la información de nombre alternativa de un archivo (su nombre de formato 8.3).
FileStreamInformation (22)	Búfer de FILE_STREAM_INFORMATION estructuras en las que se enumeran los flujos de datos de un archivo o directorio.
FileCompressionInformation (28)	Estructura FILE_COMPRESSION_INFORMATION en la que se va a devolver información de compresión para un archivo.
FileNetworkOpenInformation (34)	Estructura FILE_NETWORK_OPEN_INFORMATION . El autor de la llamada debe haber abierto el archivo con la marca FILE_READ_ATTRIBUTES especificada en el parámetro DesiredAccess .
FileAttributeTagInformation (35)	Estructura FILE_ATTRIBUTE_TAG_INFORMATION . El autor de la llamada debe haber abierto el archivo con la marca FILE_READ_ATTRIBUTES especificada en el parámetro DesiredAccess .
FileIoPriorityHintInformation (43)	Estructura FILE_IO_PRIORITY_HINT_INFORMATION . El autor de la llamada debe haber abierto el archivo con la marca FILE_READ_DATA especificada en el parámetro DesiredAccess .
FileSfioReserveInformation (44)	Estructura de FILE_SFIO_RESERVE_INFORMATION .
FileHardLinkInformation (46)	Estructura de FILE_LINKS_INFORMATION .
FileNormalizedNameInformation (48)	Estructura FILE_NAME_INFORMATION en la que se devuelve el nombre normalizado de un archivo.
FileIsRemoteDeviceInformation (51)	Estructura FILE_IS_REMOTE_DEVICE_INFORMATION . El autor de la llamada puede consultar esta información siempre que el archivo esté abierto, sin requisitos concretos para DesiredAccess.
FileStandardLinkInformation (54)	Estructura FILE_STANDARD_LINK_INFORMATION .
FileIdInformation (59)	Estructura de FILE_ID_INFORMATION .
FileDesiredStorageClassInformation (67)	Estructura FILE_DESIRED_STORAGE_CLASS_INFORMATION .
FileStatInformation (68)	FILE_STAT_INFORMATION
FileStatLxInformation (70)	FILE_STAT_LX_INFORMATION
FileCaseSensitiveInformation (71)	Estructura de FILE_CASE_SENSITIVE_INFORMATION . El autor de la llamada debe haber abierto el archivo con la marca FILE_READ_ATTRIBUTES especificada en el parámetro DesiredAccess . Este valor está disponible a partir de Windows 10, versión 1803.
FileStorageReserveIdInformation (74)	Estructura FILE_STORAGE_RESERVE_ID_INFORMATION .
FileCaseSensitiveInformationForceAccessCheck (75)	Estructura de FILE_CASE_SENSITIVE_INFORMATION . El autor de la llamada debe haber abierto el archivo con la marca FILE_READ_ATTRIBUTES especificada en el parámetro DesiredAccess . Se trata de una versión especial de la operación FileCaseSensitiveInformation que se usa para forzar al IOManager a realizar comprobaciones de acceso para el controlador en modo kernel, de forma similar a las comprobaciones que se aplican a un autor de llamada en modo de usuario. IoManager solo reconoce esta operación y un sistema de archivos nunca debe recibirla. Este valor está disponible a partir de Windows 10, versión 1803.
FileKnownFolderInformation (76)	Estructura FILE_KNOWN_FOLDER_INFORMATION . Disponible a partir de Windows Server 2022.

Valor devuelto

NtQueryInformationFile devuelve STATUS_SUCCESS o un código de error NTSTATUS adecuado.

Comentarios

NtQueryInformationFile devuelve información sobre el objeto de archivo especificado. Tenga en cuenta que devuelve cero en cualquier miembro de una estructura FILE_XXX_INFORMATION que no es compatible con un dispositivo o sistema de archivos determinado.

Cuando FileInformationClass = FileNameInformation, el nombre de archivo se devuelve en la estructura FILE_NAME_INFORMATION . La sintaxis precisa del nombre de archivo depende de varios factores:

Si abrió el archivo enviando una ruta de acceso completa a NtCreateFile, NtQueryInformationFile devuelve esa ruta de acceso completa.
Si el identificador ObjectAttributes-RootDirectory> se abrió por nombre en una llamada a NtCreateFile y, posteriormente, NtCreateFile abrió el archivo en relación con este identificador de directorio raíz, NtQueryInformationFile devuelve la ruta de acceso completa.
Si el identificador ObjectAttributes-RootDirectory> se abrió mediante el identificador de archivo (mediante la marca FILE_OPEN_BY_FILE_ID) en una llamada a NtCreateFile y, posteriormente, NtCreateFile abrió el archivo con respecto a este identificador de directorio raíz, NtQueryInformationFile devuelve la ruta de acceso relativa.
Sin embargo, si el usuario tiene SeChangeNotifyPrivilege (descrito en la documentación de Microsoft Windows SDK), NtQueryInformationFile devuelve la ruta de acceso completa en todos los casos.
Si solo se devuelve la ruta de acceso relativa, la cadena de nombre de archivo no comenzará con una barra diagonal inversa.
Si se devuelve la ruta de acceso completa y el nombre de archivo, la cadena comenzará con una sola barra diagonal inversa, independientemente de su ubicación. Por lo tanto, el archivo C:\dir1\dir2\filename.ext aparecerá como \dir1\dir2\filename.ext, mientras que el archivo \server\share\dir1\dir2\filename.ext aparecerá como \server\share\dir1\dir2\filename.ext.

Si se produce un error en NtQueryInformationFile debido a un desbordamiento del búfer, los controladores que implementan FileNameInformation deben devolver tantos caracteres WCHAR del nombre de archivo como se ajustarán al búfer y especificarán la longitud completa necesaria en el parámetro FileNameLength de la estructura FILE_NAME_INFORMATION . Debe volver a emitir la consulta mediante la longitud del nombre de archivo para que pueda recuperar el nombre de archivo completo. Los controladores que no siguen este patrón pueden requerir un aumento gradual de la longitud hasta que recuperen el nombre de archivo completo. Para obtener más información sobre cómo trabajar con archivos, vea Uso de archivos en un controlador.

Los autores de llamadas de NtQueryInformationFile deben ejecutarse en IRQL = PASSIVE_LEVEL y con las API de kernel especiales habilitadas.

Nota

Si la llamada a esta función se produce en modo de usuario, debe usar el nombre "NtQueryInformationFile" en lugar de "ZwQueryInformationFile".

En el caso de las llamadas desde controladores en modo kernel, las versiones NtXxx y ZwXxx de una rutina de Windows Native System Services pueden comportarse de forma diferente en la forma en que controlan e interpretan los parámetros de entrada. Para obtener más información sobre la relación entre las versiones NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000.
Plataforma de destino	Universal
Encabezado	ntifs.h (incluye Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte la sección Comentarios)
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs, PowerIrpDDis