Função GetFullPathNameTransactedA (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.]

Recupera o caminho completo e o nome do arquivo especificado como uma operação transacionada.

Para executar essa operação sem transações, use a função GetFullPathName .

Para obter mais informações sobre nomes de arquivo e caminho, consulte Nomes de arquivo, caminhos e namespaces.

Sintaxe

DWORD GetFullPathNameTransactedA(
  [in]  LPCSTR lpFileName,
  [in]  DWORD  nBufferLength,
  [out] LPSTR  lpBuffer,
  [out] LPSTR  *lpFilePart,
  [in]  HANDLE hTransaction
);

Parâmetros

[in] lpFileName

O nome do arquivo.

Essa cadeia de caracteres pode usar nomes curtos (o formulário 8.3) ou longos. Essa cadeia de caracteres pode ser um nome de compartilhamento ou volume.

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

O tamanho do buffer para receber a cadeia de caracteres terminada em nulo para a unidade e o caminho, em TCHARs.

[out] lpBuffer

Um ponteiro para um buffer que recebe a cadeia de caracteres terminada em nulo para a unidade e o caminho.

[out] lpFilePart

Um ponteiro para um buffer que recebe o endereço (em lpBuffer) do componente de nome de arquivo final no caminho. Especifique NULL se você não precisar receber essas informações.

Se lpBuffer apontar para um diretório e não um arquivo, lpFilePart receberá 0 (zero).

[in] hTransaction

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

Retornar valor

Se a função for bem-sucedida, o valor retornado será o comprimento, em TCHARs, da cadeia de caracteres copiada para lpBuffer, sem incluir o caractere nulo de terminação.

Se o buffer lpBuffer for muito pequeno para conter o caminho, o valor retornado será o tamanho, em TCHARs, do buffer necessário para manter o caminho e o caractere nulo de terminação.

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

Comentários

GetFullPathNameTransacted mescla o nome da unidade e do diretório atuais com um nome de arquivo especificado para determinar o caminho completo e o nome do arquivo de um arquivo especificado. Ele também calcula o endereço da parte do nome do arquivo do caminho completo e do nome do arquivo. Essa função não verifica se o caminho resultante e o nome do arquivo são válidos ou se eles veem um arquivo existente no volume associado.

Nomes de compartilhamento e volume são entrada válida para lpFileName. Por exemplo, a lista a seguir identifica o caminho e os nomes de arquivo retornados se test-2 for um computador remoto e U: é uma unidade mapeada de rede:

Se você especificar "\\test-2\q$\lh", o caminho retornado será "\\test-2\q$\lh"
Se você especificar "\\?\UNC\test-2\q$\lh", o caminho retornado será "\\?\UNC\test-2\q$\lh"
Se você especificar "U:" o caminho retornado será "U:\"

GetFullPathNameTransacted não converte o nome de arquivo especificado, lpFileName. Se o nome do arquivo especificado existir, você poderá usar GetLongPathNameTransacted, GetLongPathName ou GetShortPathName para converter em nomes de caminho longo ou curto, respectivamente.

Se o valor retornado for maior que o valor especificado em nBufferLength, você poderá chamar a função novamente com um buffer grande o suficiente para manter o caminho. Para obter um exemplo desse caso, bem como usar o buffer de comprimento zero para alocação dinâmica, consulte a seção Código de Exemplo.

Nota Embora o valor retornado nesse caso seja um comprimento que inclui o caractere nulo de terminação, o valor retornado com êxito não inclui o caractere nulo de terminação na contagem.

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.

Observação

O cabeçalho winbase.h define GetFullPathNameTransacted 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