Функция GetFullPathNameTransactedW (winbase.h)

Статья
03/08/2023

[Корпорация Майкрософт настоятельно рекомендует разработчикам использовать альтернативные средства для удовлетворения потребностей вашего приложения. Многие сценарии, для работы с которыми был разработан TxF, можно реализовать с помощью более простых и доступных методов. Кроме того, TxF может быть недоступен в будущих версиях Microsoft Windows. Дополнительные сведения и альтернативы TxF см. в разделе Альтернативы использованию транзакционной NTFS.]

Извлекает полный путь и имя указанного файла в виде транзакции.

Чтобы выполнить эту операцию без транзакций, используйте функцию GetFullPathName .

Дополнительные сведения об именах файлов и путей см. в разделе Имена файлов, пути и пространства имен.

Синтаксис

DWORD GetFullPathNameTransactedW(
  [in]  LPCWSTR lpFileName,
  [in]  DWORD   nBufferLength,
  [out] LPWSTR  lpBuffer,
  [out] LPWSTR  *lpFilePart,
  [in]  HANDLE  hTransaction
);

Параметры

[in] lpFileName

Имя файла.

Эта строка может использовать короткие (форма 8.3) или длинные имена файлов. Эта строка может быть общей папкой или именем тома.

Файл должен находиться на локальном компьютере; В противном случае функция завершается сбоем, а для последнего кода ошибки задано значение ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.

[in] nBufferLength

Размер буфера для получения строки со значением NULL для диска и пути в TCHAR.

[out] lpBuffer

Указатель на буфер, который получает строку, завершающуюся null, для диска и пути.

[out] lpFilePart

Указатель на буфер, который получает адрес (в lpBuffer) конечного компонента имени файла в пути. Укажите ЗНАЧЕНИЕ NULL , если вам не нужно получать эти сведения.

Если lpBuffer указывает на каталог, а не файл, lpFilePart получает 0 (ноль).

[in] hTransaction

Дескриптор транзакции. Этот дескриптор возвращается функцией CreateTransaction .

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение равно длине строки, скопированной в lpBuffer в TCHARs, не включая завершающий символ NULL.

Если буфер lpBuffer слишком мал, чтобы содержать путь, возвращаемое значение — это размер буфера, необходимого для хранения пути, и завершающего символа NULL в TCHAR.

Если функция завершается сбоем по какой-либо другой причине, возвращаемое значение равно нулю. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

GetFullPathNameTransacted объединяет имя текущего диска и каталога с указанным именем файла, чтобы определить полный путь и имя файла указанного файла. Он также вычисляет адрес части имени файла в полном пути и имени файла. Эта функция не проверяет допустимость результирующего пути и имени файла или наличие существующего файла на связанном томе.

Имена общих ресурсов и томов являются допустимыми входами для lpFileName. Например, следующий список удостоверений возвращает путь и имена файлов, если test-2 является удаленным компьютером, а U: — сетевым подключенным диском:

Если указать "\\test-2\q$\lh", возвращается путь "\\test-2\q$\lh".
Если указать "\\?\UNC\test-2\q$\lh", возвращается путь "\\?\UNC\test-2\q$\lh".
Если указать "U:", возвращается путь "U:\".

GetFullPathNameTransacted не преобразует указанное имя файла lpFileName. Если указанное имя файла существует, можно использовать GetLongPathNameTransacted, GetLongPathName или GetShortPathName для преобразования в длинные или короткие имена путей соответственно.

Если возвращаемое значение больше значения, указанного в nBufferLength, можно снова вызвать функцию с буфером, достаточно большим для хранения пути. Пример этого случая, а также использование буфера нулевой длины для динамического выделения см. в разделе Пример кода.

Примечание Хотя возвращаемое значение в этом случае является длиной, которая включает завершающий символ NULL, возвращаемое значение при успешном выполнении не включает завершающий символ NULL в счетчике.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология	Поддерживается
Протокол SMB 3.0	Нет
SMB 3.0 Transparent Failover (TFO)	Нет
SMB 3.0 с масштабируемыми общими папками (SO)	Нет
Файловая система общего тома кластера (CSVFS)	Нет
Восстанавливаемая файловая система (ReFS)	Нет

SMB 3.0 не поддерживает TxF.

Примечание

Заголовок winbase.h определяет GetFullPathNameTransacted в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll