Función ZwQueryInformationFile (wdm.h)

Artículo
08/08/2023

La rutina ZwQueryInformationFile devuelve varios tipos de información sobre un objeto de archivo.

Sintaxis

NTSYSAPI NTSTATUS ZwQueryInformationFile(
  [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 ZwCreateFile o ZwOpenFile.

[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 .

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.
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 .
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.
FileKnownFolderInformation (76)	Estructura FILE_KNOWN_FOLDER_INFORMATION . Disponible a partir de Windows Server 2022.

Valor devuelto

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

Comentarios

ZwQueryInformationFile 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 ZwCreateFile, ZwQueryInformationFile devuelve esa ruta de acceso completa.
Si el identificador ObjectAttributes-RootDirectory> se abrió por nombre en una llamada a ZwCreateFile y posteriormente el archivo lo abrió ZwCreateFile en relación con este identificador de directorio raíz, ZwQueryInformationFile devuelve la ruta de acceso completa.
Si el identificador objectAttributes-RootDirectory> se abrió mediante el identificador de archivo (con la marca de FILE_OPEN_BY_FILE_ID) en una llamada a ZwCreateFile y, posteriormente, el archivo lo abrió ZwCreateFile en relación con este identificador de directorio raíz, ZwQueryInformationFile devuelve la ruta de acceso relativa.
Sin embargo, si el usuario tiene SeChangeNotifyPrivilege, ZwQueryInformationFile 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 ZwQueryInformationFile 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 con 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 Usar archivos en un controlador.

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

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 Servicios del sistema nativo de Windows se pueden comportar 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
Plataforma de destino	Universal
Encabezado	wdm.h (incluya 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(storport), PowerIrpDDis(wdm)