Função SetFileAttributesTransactedA (winbase.h)

Artigo
03/03/2024

[A Microsoft recomenda fortemente que os desenvolvedores utilizem meios alternativos para atender às necessidades do aplicativo. Muitos cenários para os quais o TxF foi desenvolvido podem ser obtidos por meio de técnicas mais simples e prontamente disponíveis. Além disso, o TxF pode não estar disponível em versões futuras do Microsoft Windows. Para obter mais informações e alternativas ao TxF, confira Alternativas ao uso do NTFS transacional.]

Define os atributos de um arquivo ou diretório como uma operação transacionada.

Sintaxe

BOOL SetFileAttributesTransactedA(
  [in] LPCSTR lpFileName,
  [in] DWORD  dwFileAttributes,
  [in] HANDLE hTransaction
);

Parâmetros

[in] lpFileName

O nome do arquivo cujos atributos devem ser definidos.

Por padrão, o nome é limitado a caracteres MAX_PATH. Para estender esse limite para 32.767 caracteres largos, preencha "\\?\" para o 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 de comprimento do caminho" de Arquivos de Nomenclatura, Caminhos e Namespaces para obter detalhes.

O arquivo deve residir no computador local; caso contrário, a função falhará e o último código de erro será definido como ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.

[in] dwFileAttributes

Os atributos a serem definidos para o arquivo.

Para obter uma lista do valor do atributo de arquivo e suas descrições, consulte Constantes de atributo de 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 têm suporte nessa função. Para obter mais informações, consulte a seção Comentários.

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

FILE_ATTRIBUTE_ARCHIVE (32 (0x20))

FILE_ATTRIBUTE_HIDDEN (2 (0x2))

FILE_ATTRIBUTE_NORMAL (128 (0x80))

FILE_ATTRIBUTE_NOT_CONTENT_INDEXED (8192 (0x2000))

FILE_ATTRIBUTE_OFFLINE (4096 (0x1000))

FILE_ATTRIBUTE_READONLY (1 (0x1))

FILE_ATTRIBUTE_SYSTEM (4 (0x4))

FILE_ATTRIBUTE_TEMPORARY (256 (0x100))

[in] hTransaction

Um identificador para a transação. Esse identificador é retornado pela função CreateTransaction .

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 SetFileAttributesTransacted. Observe que essas operações não são transacionadas.

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 .

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

Para obter mais informações sobre transações, consulte NTFS transacional.

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

O SMB 3.0 não dá suporte ao TxF.

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.

Observação

O cabeçalho winbase.h define SetFileAttributesTransacted 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 Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winbase.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll