Función SetFileInformationByHandle (fileapi.h)

Artículo
08/23/2023

Establece la información de archivo del archivo especificado.

Para recuperar información de archivo mediante un identificador de archivo, vea GetFileInformationByHandle o GetFileInformationByHandleEx.

Sintaxis

BOOL SetFileInformationByHandle(
  [in] HANDLE                    hFile,
  [in] FILE_INFO_BY_HANDLE_CLASS FileInformationClass,
  [in] LPVOID                    lpFileInformation,
  [in] DWORD                     dwBufferSize
);

Parámetros

[in] hFile

Identificador del archivo para el que se va a cambiar la información.

Este identificador debe abrirse con los permisos adecuados para el cambio solicitado. Para obtener más información, vea las secciones Comentarios y Código de ejemplo.

Este identificador no debe ser un identificador de canalización.

[in] FileInformationClass

Valor de enumeración FILE_INFO_BY_HANDLE_CLASS que especifica el tipo de información que se va a cambiar.

Para obtener una tabla de valores válidos, vea la sección Comentarios.

[in] lpFileInformation

Puntero al búfer que contiene la información que se va a cambiar para la clase de información de archivo especificada. La estructura a la que apunta este parámetro corresponde a la clase especificada por FileInformationClass.

Para obtener una tabla de tipos de estructura válidos, vea la sección Comentarios.

[in] dwBufferSize

Tamaño de lpFileInformation, en bytes.

Valor devuelto

Devuelve un valor distinto de cero si es correcto o cero de lo contrario.

Para obtener información de error extendida, llame a GetLastError.

Comentarios

Ciertas clases de información de archivo se comportan de forma ligeramente diferente en diferentes versiones del sistema operativo. Estas clases son compatibles con los controladores subyacentes y cualquier información que devuelva está sujeta a cambios entre versiones del sistema operativo.

En la tabla siguiente se muestran las clases de información de archivo válidas y sus tipos de estructura de datos correspondientes para su uso con esta función.

Valor fileInformationClass	tipo lpFileInformation
FileBasicInfo 0	FILE_BASIC_INFO
FileRenameInfo 3	FILE_RENAME_INFO
FileDispositionInfo 4	FILE_DISPOSITION_INFO
FileAllocationInfo 5	FILE_ALLOCATION_INFO
FileEndOfFileInfo 6	FILE_END_OF_FILE_INFO
FileIoPriorityHintInfo 12	FILE_IO_PRIORITY_HINT_INFO

Debe especificar las marcas de acceso adecuadas al crear el identificador de archivo para su uso con SetFileInformationByHandle. Por ejemplo, si la aplicación usa FILE_DISPOSITION_INFO con el miembro DeleteFile establecido en TRUE, el archivo necesitaría el acceso DELETE solicitado en la llamada a la función CreateFile . Para ver un ejemplo de esto, consulte la sección Código de ejemplo. Para obtener más información sobre los permisos de archivo, vea Seguridad de archivos y derechos de acceso.

Si hay una transacción enlazada al identificador, la transacción de los cambios realizados se llevará a cabo para las clases de información FileBasicInfo, FileRenameInfo, FileAllocationInfo, FileEndOfFileInfo y FileDispositionInfo. Si se especifica FileDispositionInfo , solo se realiza una transacción en la operación de eliminación si se solicitó una operación DeleteFile . En este caso, si la transacción no se confirma antes de que se cierre el identificador, no se producirá la eliminación. Para obtener más información sobre TxF, vea Ntfs transaccional (TxF).

En Windows 8 y Windows Server 2012, esta función es compatible con las tecnologías siguientes.

Tecnología	Compatible
Protocolo Bloque de mensajes del servidor (SMB) 3.0	Sí
Conmutación por error transparente (TFO) de SMB 3.0	Ver comentario
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)	Ver comentario
Sistema de archivos de Volumen compartido de clúster (CsvFS)	Sí
Sistema de archivos resistente a errores (ReFS)	Sí

SMB 3.0 no admite el cambio de nombre de flujos de datos alternativos en recursos compartidos de archivos con capacidad de disponibilidad continua.

Ejemplos

En el siguiente ejemplo de C++ se muestra cómo crear un archivo y marcarlo para su eliminación cuando se cierra el identificador.

//...
  HANDLE hFile = CreateFile( TEXT("tempfile"), 
                             GENERIC_READ | GENERIC_WRITE | DELETE,
                             0 /* exclusive access */,
                             NULL, 
                             CREATE_ALWAYS,
                             0, 
                             NULL);

  if (hFile != INVALID_HANDLE_VALUE)
   {
    FILE_DISPOSITION_INFO fdi;
    fdi.DeleteFile = TRUE; // marking for deletion

    BOOL fResult = SetFileInformationByHandle( hFile, 
                                               FileDispositionInfo, 
                                               &fdi, 
                                               sizeof(FILE_DISPOSITION_INFO) );

    if (fResult)
     {
      // File will be deleted upon CloseHandle.
      _tprintf( TEXT("SetFileInformationByHandle marked tempfile for deletion\n") );

      // ... 
      // Now use the file for whatever temp data storage you need,
      // it will automatically be deleted upon CloseHandle or 
      // application termination.
      // ...
     }
    else
     {
      _tprintf( TEXT("error %lu:  SetFileInformationByHandle could not mark tempfile for deletion\n"), 
                GetLastError() );
     }

    CloseHandle(hFile); 

    // At this point, the file is closed and deleted by the system.
   }
  else 
   {
    _tprintf( TEXT("error %lu:  could not create tempfile\n"), 
              GetLastError() );
 }
//...

Requisitos


Cliente mínimo compatible	Windows Vista [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2008 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	fileapi.h (incluya Windows.h)
Library	Kernel32.lib; FileExtd.lib en Windows Server 2003 y Windows XP
Archivo DLL	Kernel32.dll
Redistribuible	Windows SDK en Windows Server 2003 y Windows XP.