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

Статья
06/02/2023

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

Преобразует указанный путь в длинную форму в виде транзакции операции.

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

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

Синтаксис

DWORD GetLongPathNameTransactedA(
  [in]  LPCSTR lpszShortPath,
  [out] LPSTR  lpszLongPath,
  [in]  DWORD  cchBuffer,
  [in]  HANDLE hTransaction
);

Параметры

[in] lpszShortPath

Путь для преобразования.

По умолчанию имя ограничено MAX_PATH символами. Чтобы расширить это ограничение до 32 767 символов в ширину, добавьте к пути "\\?\". Дополнительные сведения см. в статье Именование файлов, путей и пространств имен.

Совет

Начиная с Windows 10 версии 1607, вы можете согласиться на удаление ограничения MAX_PATH без добавления "\\?\". Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" статьи Именование файлов, путей и пространств имен .

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

[out] lpszLongPath

Указатель на буфер для получения длинного пути.

Можно использовать тот же буфер, который использовался для параметра lpszShortPath .

[in] cchBuffer

Размер буфера lpszLongPath указывает на в TCHARs.

[in] hTransaction

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

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

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

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

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

Во многих файловых системах короткое имя файла содержит символ тильды (~). Однако не все файловые системы следуют этому соглашению. Поэтому не следует предполагать, что можно пропустить вызов GetLongPathNameTransacted , если путь не содержит символ тильды (~).

Если длинный путь не найден, эта функция возвращает имя, указанное в параметре lpszShortPath в параметре lpszLongPath .

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

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

Можно иметь доступ к файлу или каталогу, но не иметь доступа к некоторым родительским каталогам этого файла или каталога. В результате GetLongPathNameTransacted может завершиться ошибкой, если не удается запросить родительский каталог компонента пути для определения длинного имени этого компонента. Этот проверка можно пропустить для компонентов каталога с расширениями файлов длиной более 3 символов или общей длиной более 12 символов. Дополнительные сведения см. в разделе Короткие и длинные имена статьи Именование файлов, путей и пространств имен.

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

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

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

Примечание

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

Требования

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

См. также

Функции управления файлами

GetFullPathNameTransacted

GetShortPathName

Именование файлов, путей и пространств имен

Поддержка транзакций в NTFS