Função SetFileInformationByHandle (fileapi.h)

Artigo
08/23/2023

Define as informações do arquivo especificado.

Para recuperar informações de arquivo usando um identificador de arquivo, consulte GetFileInformationByHandle ou GetFileInformationByHandleEx.

Sintaxe

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

Parâmetros

[in] hFile

Um identificador para o arquivo para o qual as informações serão alteradas.

Esse identificador deve ser aberto com as permissões apropriadas para a alteração solicitada. Para obter mais informações, consulte as seções Comentários e Código de Exemplo.

Esse identificador não deve ser uma alça de pipe.

[in] FileInformationClass

Um FILE_INFO_BY_HANDLE_CLASS valor de enumeração que especifica o tipo de informação a ser alterado.

Para obter uma tabela de valores válidos, consulte a seção Comentários.

[in] lpFileInformation

Um ponteiro para o buffer que contém as informações a serem alteradas para a classe de informações de arquivo especificada. A estrutura para a qual esse parâmetro aponta corresponde à classe especificada por FileInformationClass.

Para obter uma tabela de tipos de estrutura válidos, consulte a seção Comentários.

[in] dwBufferSize

O tamanho de lpFileInformation, em bytes.

Valor retornado

Retornará diferente de zero se tiver êxito ou zero caso contrário.

Para obter informações de erro estendidas, chame GetLastError.

Comentários

Determinadas classes de informações de arquivo se comportam um pouco diferente em diferentes versões do sistema operacional. Essas classes têm suporte dos drivers subjacentes e todas as informações retornadas estão sujeitas a alterações entre as versões do sistema operacional.

A tabela a seguir mostra as classes de informações de arquivo válidas e seus tipos de estrutura de dados correspondentes para uso com essa função.

Valor de 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

Você deve especificar os sinalizadores de acesso apropriados ao criar o identificador de arquivo para uso com SetFileInformationByHandle. Por exemplo, se o aplicativo estiver usando FILE_DISPOSITION_INFO com o membro DeleteFile definido como TRUE, o arquivo precisará do acesso DELETE solicitado na chamada para a função CreateFile . Para ver um exemplo disso, consulte a seção Código de Exemplo. Para obter mais informações sobre permissões de arquivo, consulte Segurança de arquivo e direitos de acesso.

Se houver uma transação associada ao identificador, as alterações feitas serão transacionadas para as classes de informações FileBasicInfo, FileRenameInfo, FileAllocationInfo, FileEndOfFileInfo e FileDispositionInfo. Se FileDispositionInfo for especificado, somente a operação de exclusão será transacionada se uma operação DeleteFile tiver sido solicitada. Nesse caso, se a transação não for confirmada antes que o identificador seja fechado, a exclusão não ocorrerá. Para obter mais informações sobre TxF, consulte NTFS transacional (TxF).

No Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.

Tecnologia	Com suporte
Protocolo SMB (SMB) 3.0	Sim
TFO (Failover transparente) do SMB 3.0	Ver comentário
SMB 3.0 com compartilhamentos de arquivos de expansão (SO)	Ver comentário
Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS)	Sim
ReFS (Sistema de Arquivos Resiliente)	Sim

O SMB 3.0 não dá suporte à renomeação de fluxos de dados alternativos em compartilhamentos de arquivos com funcionalidade de disponibilidade contínua.

Exemplos

O exemplo C++ a seguir mostra como criar um arquivo e marcá-lo para exclusão quando o identificador é fechado.

//...
  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 com suporte	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	fileapi.h (inclua Windows.h)
Biblioteca	Kernel32.lib; FileExtd.lib no Windows Server 2003 e Windows XP
DLL	Kernel32.dll
Redistribuível	SDK do Windows no Windows Server 2003 e Windows XP.