Función ZwSetInformationFile (wdm.h)

Artículo
11/07/2024

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

Sintaxis

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

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

Valor de FileInformationClass	Significado
FileBasicInformation de	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.
FileDispositionInformation de	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.
FileDispositionInformationEx de	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.
FileEndOfFileInformation	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.
FileIoPriorityHintInformation	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.
FileLinkInformation	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.
FilePositionInformation	Cambie la información del archivo actual, que se almacena en una estructura de FILE_POSITION_INFORMATION.
FileRenameInformation de	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.
FileShortNameInformation	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 .
FileIoCompletionNotificationInformation	Cambie las marcas de notificación de finalización de E/S del archivo. Admite las mismas marcas que SetFileCompletionNotificationModes.
FileValidDataLengthInformation de	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.
fileReplaceCompletionInformation	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ón createIoCompletionPort .

Valor devuelto

ZwSetInformationFile devuelve STATUS_SUCCESS o un estado de error adecuado.

Observaciones

ZwSetInformationFile 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 ZwClose 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 ZwCreateFile incluía la marca FILE_NO_INTERMEDIATE_BUFFERING en el parámetro CreateOptions, se aplican ciertas restricciones en el miembro CurrentByteOff set de la estructura de FILE_POSITION_INFORMATION. Para obtener más información, vea ZwCreateFile.

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, ZwSetInformationFile 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 ZwSetInformationFile deben ejecutarse en IRQL = PASSIVE_LEVEL y con API de kernel especiales habilitadas.

Si la llamada a esta función se produce en modo de usuario, debe usar 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
de la plataforma de destino de	Universal
encabezado de	wdm.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(storport), PowerIrpDDis(wdm)