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

Статья
08/27/2023

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

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

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

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

Синтаксис

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

Параметры

[in] lpFileName

Имя файла.

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

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

[in] nBufferLength

Размер буфера для получения строки, заканчивающейся значением NULL, для диска и пути в TCHARs.

[out] lpBuffer

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

[out] lpFilePart

Указатель на буфер, получающий адрес (в lpBuffer) конечного компонента имени файла в пути. Укажите значение NULL , если получать эти сведения не требуется.

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

[in] hTransaction

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

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

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

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

Если функция завершается сбоем по какой-либо другой причине, возвращаемое значение равно нулю. Дополнительные сведения об ошибке можно получить, вызвав 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	Нет
Прозрачная отработка отказа (TFO) SMB 3.0	Нет
SMB 3.0 с масштабируемыми общими папками (SO)	Нет
Файловая система общего тома кластера (CSVFS)	Нет
Восстанавливаемая файловая система (ReFS)	Нет

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

Примечание

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

Требования

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