Función NtQueryInformationFile (ntifs.h)

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):

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.

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

Consulte también

FILE_ACCESS_INFORMATION

FILE_ALIGNMENT_INFORMATION

FILE_ALL_INFORMATION

FILE_ATTRIBUTE_TAG_INFORMATION

FILE_BASIC_INFORMATION

FILE_EA_INFORMATION

FILE_INTERNAL_INFORMATION

FILE_IO_PRIORITY_HINT_INFORMATION

FILE_IS_REMOTE_DEVICE_INFORMATION

FILE_MODE_INFORMATION

FILE_NAME_INFORMATION

FILE_NETWORK_OPEN_INFORMATION

FILE_POSITION_INFORMATION

FILE_STANDARD_INFORMATION

Uso de las versiones Nt y Zw de las rutinas nativas de System Services

NtCreateFile

NtQueryInformationByName

NtSetInformationFile