Função CreateHardLinkTransactedA (winbase.h)

Artigo
11/20/2024

[A Microsoft recomenda fortemente que os desenvolvedores utilizem meios alternativos para alcançar as 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, consulte Alternativas para usar o NTFS transacional.]

Estabelece um vínculo rígido entre um arquivo existente e um novo arquivo como uma operação transacionada. Essa função só tem suporte no sistema de arquivos NTFS e somente para arquivos, não para diretórios.

Sintaxe

BOOL CreateHardLinkTransactedA(
  [in] LPCSTR                lpFileName,
  [in] LPCSTR                lpExistingFileName,
       LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in] HANDLE                hTransaction
);

Parâmetros

[in] lpFileName

O nome do novo arquivo.

Esse parâmetro não pode especificar o nome de um diretório.

[in] lpExistingFileName

O nome do arquivo existente.

Esse parâmetro não pode especificar o nome de um diretório.

lpSecurityAttributes

Reservado; deve ser NULL.

[in] hTransaction

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

Valor de retorno

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

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

O número máximo de links rígidos que podem ser criados com essa função é 1023 por arquivo. Se mais de 1023 links forem criados para um arquivo, um erro resultará.

Os arquivos devem 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.

Observações

Qualquer entrada de diretório para um arquivo criado com CreateFileTransacted ou CreateHardLinkTransacted é um link rígido para um arquivo associado. Um link rígido adicional criado com a função CreateHardLinkTransacted permite que você tenha várias entradas de diretório para um arquivo, ou seja, vários links rígidos para o mesmo arquivo, que podem ser nomes diferentes no mesmo diretório ou os mesmos nomes ou nomes diferentes em diretórios diferentes. No entanto, todos os links rígidos para um arquivo devem estar no mesmo volume.

Como os links rígidos são apenas entradas de diretório para um arquivo, quando um aplicativo modifica um arquivo por meio de qualquer link rígido, todos os aplicativos que usam qualquer outro link rígido para o arquivo veem as alterações. Além disso, todas as entradas de diretório serão atualizadas se o arquivo for alterado. Por exemplo, se um tamanho de arquivo for alterado, todos os links rígidos para o arquivo mostrarão o novo tamanho do arquivo.

O descritor de segurança pertence ao arquivo ao qual um link rígido aponta. O link em si é apenas uma entrada de diretório e não tem um descritor de segurança. Portanto, ao alterar o descritor de segurança de um link rígido, você altera o descritor de segurança do arquivo subjacente e todos os links rígidos que apontam para o arquivo permitem o acesso recém-especificado. Não é possível fornecer descritores de segurança diferentes a um arquivo por link rígido.

Essa função não modifica o descritor de segurança do arquivo ao qual estar vinculado, mesmo que as informações do descritor de segurança sejam passadas no parâmetro lpSecurityAttributes.

Use DeleteFileTransacted para excluir links rígidos. Você pode excluí-las em qualquer ordem, independentemente da ordem em que elas são criadas.

Sinalizadores, atributos, acesso e compartilhamento especificados em CreateFileTransacted operam por arquivo. Ou seja, se você abrir um arquivo que não permite o compartilhamento, outro aplicativo não poderá compartilhar o arquivo criando um novo link rígido para o arquivo.

Quando você cria um link rígido no sistema de arquivos NTFS, as informações de atributo de arquivo na entrada do diretório são atualizadas somente quando o arquivo é aberto ou quando GetFileInformationByHandle é chamado com o identificador de um arquivo específico.

links simbólicos: Se o caminho apontar para um vínculo simbólico, a função criará um vínculo rígido com o destino.

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

Tecnologia	Suportado
Protocolo SMB (Bloco de Mensagens do Servidor) 3.0	Não
TFO (Failover Transparente) do SMB 3.0	Não
SMB 3.0 com Compartilhamentos de Arquivos de Expansão (SO)	Não
Sistema de Arquivos de Volume Compartilhado de Cluster (CsvFS)	Não
ReFS (Sistema de Arquivos Resiliente)	Não

Observe que o SMB 3.0 não dá suporte ao TxF.

Nota

O cabeçalho winbase.h define CreateHardLinkTransacted como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Vista [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2008 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	winbase.h (inclua Windows.h)
biblioteca	Kernel32.lib
de DLL	Kernel32.dll