Função SetFileAttributesW (fileapi.h)

Artigo
06/02/2023

Define os atributos de um arquivo ou diretório.

Para executar essa operação como uma operação transacionada, use a função SetFileAttributesTransacted .

Sintaxe

BOOL SetFileAttributesW(
  [in] LPCWSTR lpFileName,
  [in] DWORD   dwFileAttributes
);

Parâmetros

[in] lpFileName

O nome do arquivo cujos atributos devem ser definidos.

Por padrão, o nome é limitado a MAX_PATH caracteres. Para estender esse limite para 32.767 caracteres largos, acrescente "\\?\" ao caminho. Para obter mais informações, confira Nomear arquivos, caminhos e namespaces.

Dica

A partir do Windows 10, versão 1607, você pode optar por remover a limitação de MAX_PATH sem acrescentar "\\?\". Consulte a seção "Limitação máxima do comprimento do caminho" de Arquivos de Nomenclatura, Caminhos e Namespaces para obter detalhes.

[in] dwFileAttributes

Os atributos a serem definidos para o arquivo.

Esse parâmetro pode ser um ou mais valores, combinados usando o operador OR bit a bit. No entanto, todos os outros valores substituem FILE_ATTRIBUTE_NORMAL.

Nem todos os atributos são compatíveis com essa função. Para obter mais informações, consulte a seção Comentários.

Veja a seguir uma lista de valores de atributo com suporte.

Valor	Significado
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)	Um arquivo ou diretório que é um arquivo morto ou diretório. Os aplicativos normalmente usam esse atributo para marcar arquivos para backup ou remoção.
FILE_ATTRIBUTE_HIDDEN 2 (0x2)	O arquivo ou diretório está oculto. Ele não está incluído em uma listagem de diretórios comuns.
FILE_ATTRIBUTE_NORMAL 128 (0x80)	Um arquivo que não tem outros atributos definidos. Este atributo é válido somente quando for usado sozinho.
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 8192 (0x2000)	O arquivo ou diretório não deve ser indexado pelo serviço de indexação de conteúdo.
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)	Os dados de um arquivo não estão disponíveis imediatamente. Esse atributo indica que os dados do arquivo são movidos fisicamente para o armazenamento offline. Esse atributo é usado pelo armazenamento remoto, que é o software de gerenciamento de armazenamento hierárquico. Os aplicativos não devem alterar esse atributo arbitrariamente.
FILE_ATTRIBUTE_READONLY 1 (0x1)	Um arquivo que é somente leitura. Os aplicativos podem ler o arquivo, mas não podem gravar nele nem excluí-lo. Esse atributo não é respeitado em diretórios. Para obter mais informações, confira "Você não pode exibir ou alterar os atributos Somente leitura ou Sistema de pastas no Windows Server 2003, no Windows XP ou no Windows Vista.
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	Um arquivo ou diretório do qual o sistema operacional usa uma parte ou usa exclusivamente.
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	Um arquivo que está sendo usado para armazenamento temporário. Os sistemas de arquivos evitam gravar dados de volta no armazenamento em massa se houver memória de cache suficiente disponível, pois, normalmente, um aplicativo exclui um arquivo temporário depois que o identificador é fechado. Nesse cenário, o sistema pode evitar totalmente gravar os dados. Caso contrário, os dados serão gravados depois que o identificador for fechado.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

A tabela a seguir descreve como definir os atributos que não podem ser definidos usando SetFileAttributes. Para obter uma lista completa de todos os valores de atributo de arquivo e suas descrições, consulte Constantes de atributo de arquivo.

Atributo	Como definir
FILE_ATTRIBUTE_COMPRESSED 0x800	Para definir o estado de compactação de um arquivo, use a função DeviceIoControl com a operação FSCTL_SET_COMPRESSION .
FILE_ATTRIBUTE_DEVICE 0x40	Reservado; não use.
FILE_ATTRIBUTE_DIRECTORY 0x10	Os arquivos não podem ser convertidos em diretórios. Para criar um diretório, use a função CreateDirectory ou CreateDirectoryEx .
FILE_ATTRIBUTE_ENCRYPTED 0x4000	Para criar um arquivo criptografado, use a função CreateFile com o atributo FILE_ATTRIBUTE_ENCRYPTED . Para converter um arquivo existente em um arquivo criptografado, use a função EncryptFile .
FILE_ATTRIBUTE_REPARSE_POINT 0x400	Para associar um ponto de nova análise a um arquivo ou diretório, use a função DeviceIoControl com a operação FSCTL_SET_REPARSE_POINT .
FILE_ATTRIBUTE_SPARSE_FILE 0x200	Para definir o atributo esparso de um arquivo, use a função DeviceIoControl com a operação FSCTL_SET_SPARSE .

Operações transacionadas

Se um arquivo estiver aberto para modificação em uma transação, nenhum outro thread poderá abrir o arquivo para modificação até que a transação seja confirmada. Portanto, se um thread transacionado abrir o arquivo primeiro, todos os threads subsequentes que tentarem modificar o arquivo antes que a transação seja confirmada receberão uma violação de compartilhamento. Se um thread não transacionado modificar o arquivo antes do thread transacionado e o arquivo ainda estiver aberto quando a transação tentar abri-lo, a transação receberá o erro ERROR_TRANSACTIONAL_CONFLICT.

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	Sim
SMB 3.0 com compartilhamentos de arquivos de expansão (SO)	Sim
Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS)	Sim
ReFS (Sistema de Arquivos Resiliente)	Sim

Exemplos

Para obter um exemplo, consulte Recuperando e alterando atributos de arquivo.

Observação

O cabeçalho fileapi.h define SetFileAttributes como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	fileapi.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll