Función NtSetInformationFile (ntifs.h)

Artículo
02/07/2025

El NtSetInformationFile rutina cambia varios tipos de información sobre un objeto de archivo.

Sintaxis

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

Parámetros

[in] FileHandle

Identificador del objeto de archivo. Este identificador se crea mediante una llamada correcta a ntCreateFile o ntOpenFile.

[out] IoStatusBlock

Puntero a una estructura IO_STATUS_BLOCK que recibe el estado de finalización final e información sobre la operación solicitada. El miembro Information recibe el número de bytes establecidos en el archivo.

[in] FileInformation

Puntero a un búfer que contiene la información que se va a establecer para el archivo. La estructura concreta de este búfer viene determinada por el parámetro FileInformationClass. Por ejemplo, si el parámetro FileInformationClass se establece en la constante FileDispositionInformationEx, este parámetro debe ser un puntero a una estructura FILE_DISPOSITION_INFORMATION_EX.

[in] Length

Tamaño, en bytes, del búfer de FileInformation.

[in] FileInformationClass

Tipo de información, proporcionado en el búfer al que apunta FileInformation, que se va a establecer para el archivo. Los controladores intermedios y de dispositivo pueden especificar cualquiera de los siguientes valores de FILE_INFORMATION_CLASS.

valor de FILE_INFORMATION_CLASS	Tipo de información devuelta
fileBasicInformation (4)	Cambie la información proporcionada en una estructura de FILE_BASIC_INFORMATION. El autor de la llamada debe haber abierto el archivo con la marca FILE_WRITE_ATTRIBUTES establecida en el parámetro DesiredAccess.
FileRenameInformation (10)	Cambie el nombre de archivo actual, que se proporciona en una estructura de FILE_RENAME_INFORMATION. El autor de la llamada debe tener acceso DELETE al archivo.
fileDispositionInformation (13)	Solicite eliminar el archivo cuando se cierre o cancele una eliminación solicitada anteriormente. La opción de eliminar o cancelar se proporciona en una estructura de FILE_DISPOSITION_INFORMATION. El autor de la llamada debe haber abierto el archivo con la marca DELETE establecida en el parámetro DesiredAccess.
filePositionInformation (14)	Cambie la información del archivo actual, que se almacena en una estructura de FILE_POSITION_INFORMATION.
FileEndOfFileInformation (20)	Cambie la información actual del final del archivo, proporcionada en una estructura de FILE_END_OF_FILE_INFORMATION. La operación puede truncar o extender el archivo. El autor de la llamada debe haber abierto el archivo con la marca FILE_WRITE_DATA establecida en el parámetro DesiredAccess.
fileValidDataLengthInformation (39)	Cambie la longitud de datos válida actual para el archivo, que se proporciona en una estructura de FILE_VALID_DATA_LENGTH_INFORMATION. El archivo debe estar en un volumen NTFS y el autor de la llamada debe haber abierto el archivo con la marca FILE_WRITE_DATA establecida en el parámetro desiredAccess de. Los usuarios que no son administradores y remotos deben tener el privilegio SeManageVolumePrivilege.
fileShortNameInformation (40)	Cambie el nombre de archivo corto actual, que se proporciona en una estructura de FILE_NAME_INFORMATION. El archivo debe estar en un volumen NTFS y el autor de la llamada debe haber abierto el archivo con la marca DesiredAccess DELETE establecida en el parámetro DesiredAccess.
FileIoPriorityHintInformation (43)	Cambie la sugerencia de prioridad IRP predeterminada actual para el identificador de archivo. El nuevo valor se proporciona en una estructura FILE_IO_PRIORITY_HINT_INFORMATION. Esta estructura debe estar alineada con 8 bytes.
FileReplaceCompletionInformation (61)	Cambie o quite el puerto de finalización de E/S para el identificador de archivo especificado. El autor de la llamada proporciona un puntero a una estructura de FILE_COMPLETION_INFORMATION que especifica un identificador de puerto y una clave de finalización. Si el identificador de puerto no es NULL, este identificador especifica un nuevo puerto de finalización de E/S que se va a asociar al identificador de archivo. Para quitar el puerto de finalización de E/S asociado al identificador de archivo, establezca el identificador de puerto en la estructura en NULL. Para obtener un identificador de puerto, un llamador en modo de usuario puede llamar a la funcióncreateIoCompletionPort.
fileDispositionInformationEx (64)	Solicite eliminar el archivo o cancelar una eliminación solicitada anteriormente. La opción de eliminar o cancelar, así como la configuración de cuándo y cómo se debe realizar la eliminación, se proporcionan en una estructura de FILE_DISPOSITION_INFORMATION_EX. El autor de la llamada debe haber abierto el archivo con la marca DELETE establecida en el parámetro DesiredAccess.
FileCaseSensitiveInformation (71)	Cambie la información proporcionada en una estructura de FILE_CASE_SENSITIVE_INFORMATION. El autor de la llamada debe haber abierto el archivo con la marca FILE_WRITE_ATTRIBUTES establecida en el parámetro DesiredAccess. Este valor está disponible a partir de Windows 10, versión 1803.
FileLinkInformation (72)	Cree un vínculo físico a un archivo existente, que se especifica en una estructura FILE_LINK_INFORMATION. No todos los sistemas de archivos admiten vínculos físicos; por ejemplo, NTFS hace mientras FAT no lo hace.
FileCaseSensitiveInformationForceAccessCheck (75)	Cambie la información proporcionada en una estructura de FILE_CASE_SENSITIVE_INFORMATION. El autor de la llamada debe haber abierto el archivo con la marca FILE_WRITE_ATTRIBUTES establecida 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, 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

NtSetInformationFile devuelve STATUS_SUCCESS o un estado de error adecuado.

Observaciones

NtSetInformationFile cambia la información sobre un archivo. Omite cualquier miembro de una estructura de FILE_XXX_INFORMATION que no sea compatible con un dispositivo o sistema de archivos determinado.

Si establece FileInformationClass en FileDispositionInformation, posteriormente puede pasar FileHandle a NtClose pero no a ninguna otra rutina de ZwXxxFile. Dado que FileDispositionInformation hace que el archivo se marque para su eliminación, se trata de un error de programación para intentar cualquier operación posterior en el identificador que no sea cerrarlo.

Si establece FileInformationClass en FilePositionInformationy la llamada anterior a NtCreateFile incluía la marca FILE_NO_INTERMEDIATE_BUFFERING en el parámetro CreateOptions, se aplican ciertas restricciones en el miembro CurrentByteOff set del FILE_POSITION_INFORMATION estructura. Para obtener más información, vea ntCreateFile.

Si establece FileInformationClass en FileEndOfFileInformationy el miembro EndOfFile de FILE_END_OF_FILE_INFORMATION especifica un desplazamiento más allá de la marca de fin de archivo actual, NtSetInformationFile extiende el archivo y rellena la extensión con ceros.

Para obtener más información sobre cómo trabajar con archivos, vea Using Files in a Driver.

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

Nota

Si la llamada a esta función se produce en modo de usuario, use el nombre "NtSetInformationFile" en lugar de "ZwSetInformationFile".

En el caso de las llamadas desde controladores en modo kernel, las NtXxx y Zwversiones de Xxx de una rutina de Servicios del sistema nativo de Windows 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 de NtXxx*** y ZwXxx*** de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000.
de la plataforma de destino de	Universal
encabezado de	ntifs.h (include Wdm.h, Ntddk.h, Ntifs.h)
biblioteca de	NtosKrnl.lib
DLL de	NtosKrnl.exe
irQL	PASSIVE_LEVEL (consulte la sección Comentarios)
reglas de cumplimiento de DDI	HwStorPortProhibitedDIs, PowerIrpDDis