Função CreateHardLinkTransactedW (winbase.h)

Artigo
08/27/2023

[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.]

Estabelece um link físico 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 apenas para arquivos, não para diretórios.

Sintaxe

BOOL CreateHardLinkTransactedW(
  [in] LPCWSTR               lpFileName,
  [in] LPCWSTR               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

Reservados; deve ser NULL.

[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á 0 (zero). 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.

Comentários

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, quando você altera 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. Você não pode fornecer a um arquivo diferentes descritores de segurança 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í-los 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 link simbólico, a função criará um link rígido para o destino.

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	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 Clusterizado (CsvFS)	Não
ReFS (Sistema de Arquivos Resiliente)	Não

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

Observação

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


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