Função SetFileInformationByHandle (fileapi.h)

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.

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.

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

Confira também

CreateFile

Funções de gerenciamento de arquivos

Segurança de arquivo e direitos de acesso

Direitos de acesso genéricos

GetFileInformationByHandle

GetFileInformationByHandleEx