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

Статья
11/20/2024

[Корпорация Майкрософт настоятельно рекомендует разработчикам использовать альтернативные средства для достижения потребностей вашего приложения. Многие сценарии, для которые 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.

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

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

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

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

Замечания

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

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

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

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

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

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

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

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2008 [только классические приложения]
целевая платформа	Виндоус
заголовка	winbase.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll

См. также

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

GetFullPathNameTransacted

GetShortPathName

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

транзакционных NTFS

Поделиться через