GetFullPathNameTransactedA 함수(winbase.h)

아티클
08/27/2023

[Microsoft는 개발자가 애플리케이션의 요구 사항을 달성하기 위해 대체 수단을 활용하는 것이 좋습니다. TxF가 개발된 많은 시나리오는 더 간단하고 쉽게 사용할 수 있는 기술을 통해 달성할 수 있습니다. 또한 이후 버전의 Microsoft Windows에서는 TxF를 사용하지 못할 수도 있습니다. 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

TCHAR에서 드라이브 및 경로에 대해 null로 끝나는 문자열을 수신할 버퍼의 크기입니다.

[out] lpBuffer

드라이브 및 경로에 대해 null로 끝나는 문자열을 수신하는 버퍼에 대한 포인터입니다.

[out] lpFilePart

경로에 있는 최종 파일 이름 구성 요소의 주소( lpBuffer)를 수신하는 버퍼에 대한 포인터입니다. 이 정보를 받을 필요가 없는 경우 NULL 을 지정합니다.

lpBuffer가 파일이 아닌 디렉터리를 가리키는 경우 lpFilePart는 0을 받습니다.

[in] hTransaction

트랜잭션에 대한 핸들입니다. 이 핸들은 CreateTransaction 함수에서 반환됩니다.

반환 값

함수가 성공하면 반환 값은 종료 null 문자를 포함하지 않고 lpBuffer에 복사된 문자열의 길이(TCHAR)입니다.

lpBuffer 버퍼가 너무 작아서 경로를 포함할 수 없는 경우 반환 값은 경로 및 종료 null 문자를 보유하는 데 필요한 버퍼의 크기(TCHAR)입니다.

다른 이유로 인해 함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

GetFullPathNameTransacted 는 현재 드라이브 및 디렉터리의 이름을 지정된 파일 이름과 병합하여 지정된 파일의 전체 경로와 파일 이름을 확인합니다. 또한 전체 경로 및 파일 이름의 파일 이름 부분의 주소를 계산합니다. 이 함수는 결과 경로 및 파일 이름이 유효한지 또는 연결된 볼륨에 기존 파일이 표시되는지 확인하지 않습니다.

공유 및 볼륨 이름은 lpFileName에 유효한 입력입니다. 예를 들어 test-2가 원격 컴퓨터이고 U인 경우 다음 목록은 반환된 경로 및 파일 이름을 ID로 지정합니다. 는 네트워크 매핑 드라이브입니다.

"\\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에 지정된 값보다 큰 경우 경로를 보유할 수 있을 만큼 큰 버퍼를 사용하여 함수를 다시 호출할 수 있습니다. 이 사례의 예는 동적 할당에 길이가 0인 버퍼를 사용하는 것뿐 아니라 예제 코드 섹션을 참조하세요.

참고 이 경우 반환 값은 종료 null 문자를 포함하는 길이이지만 성공의 반환 값에는 종료 null 문자가 개수에 포함되지 않습니다.

Windows 8 및 Windows Server 2012에서 이 함수는 다음 기술을 통해 지원됩니다.

기술	지원됨
SMB(서버 메시지 블록) 3.0 프로토콜	No
SMB 3.0 TFO(투명 장애 조치(failover))	No
SO(스케일 아웃 파일 공유)를 사용하는 SMB 3.0	No
CsvFS(클러스터 공유 볼륨 파일 시스템)	No
ReFS(Resilient File System)	No

SMB 3.0은 TxF를 지원하지 않습니다.

참고

winbase.h 헤더는 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 GetFullPathNameTransacted를 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	winbase.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll