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

Статья
11/20/2024

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

[out] lpBuffer

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

[out] lpFilePart

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

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

[in] hTransaction

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

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

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

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

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

Замечания

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

Имена общих ресурсов и томов являются допустимыми входами для lpFileName. Например, следующий список удостоверяет возвращаемый путь и имена файлов, если тест-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, можно снова вызвать функцию с буфером, который достаточно велик для хранения пути. Пример этого дела, а также использование буфера нулевой длины для динамического выделения см. в разделе "Пример кода".

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

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

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

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

Заметка

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

Требования

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