Función SetFileInformationByHandle (fileapi.h)

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.

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.

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

Consulte también

CreateFile

Funciones de administración de archivos

Seguridad y derechos de acceso de los archivos

Derechos de acceso genéricos

GetFileInformationByHandle

GetFileInformationByHandleEx