GetVolumePathNameW 함수(fileapi.h)

아티클
02/29/2024

지정된 경로가 탑재되는 볼륨 탑재 지점을 검색합니다.

구문

BOOL GetVolumePathNameW(
  [in]  LPCWSTR lpszFileName,
  [out] LPWSTR  lpszVolumePathName,
  [in]  DWORD   cchBufferLength
);

매개 변수

[in] lpszFileName

입력 경로 문자열에 대한 포인터입니다. 절대 파일과 상대 파일 및 디렉터리 이름(예: "..")은 모두 이 경로에서 허용됩니다.

볼륨 한정자 없이 상대 디렉터리 또는 파일 이름을 지정하는 경우 GetVolumePathName 은 부팅 볼륨의 드라이브 문자를 반환합니다.

이 매개 변수가 빈 문자열 ""인 경우 함수는 실패하지만 마지막 오류는 ERROR_SUCCESS 설정됩니다.

[out] lpszVolumePathName

입력 경로의 볼륨 탑재 지점을 수신하는 문자열에 대한 포인터입니다.

[in] cchBufferLength

TCHAR의 출력 버퍼 길이입니다.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

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

설명

지정된 경로가 전달되면 GetVolumePathName 은 볼륨 탑재 지점에 대한 경로를 반환합니다. 즉, 지정된 경로의 끝점이 있는 볼륨의 루트를 반환합니다.

예를 들어 에 탑재된 볼륨 D와 에 C:\Mnt\Ddrive 탑재된 볼륨 E가 C:\Mnt\Ddrive\Mnt\Edrive있다고 가정합니다. 또한 경로 E:\Dir\Subdir\MyFile가 인 파일이 있다고 가정합니다. GetVolumePathName에 전달 C:\Mnt\Ddrive\Mnt\Edrive\Dir\Subdir\MyFile 하면 경로C:\Mnt\Ddrive\Mnt\Edrive\가 반환됩니다.

상대 디렉터리 또는 파일이 볼륨 한정자 없이 전달되는 경우 함수는 부팅 볼륨의 드라이브 문자를 반환합니다. 잘못된 파일 또는 디렉터리 이름이 유효한 볼륨 한정자 없이 지정된 경우에도 부팅 볼륨의 드라이브 문자가 반환됩니다. 유효한 볼륨 지정자가 지정되고 볼륨이 있지만 잘못된 파일 또는 디렉터리 이름을 지정하면 함수가 성공하고 해당 볼륨 이름이 반환됩니다. 예제는 이 항목의 예제 섹션을 참조하세요.

유효한 Win32 네임스페이스 경로를 지정해야 합니다. NT 네임스페이스 경로(예 \DosDevices\H: : 또는 \Device\HardDiskVolume6)를 지정하면 함수는 해당 NT 네임스페이스 경로의 드라이브 문자가 아닌 부팅 볼륨의 드라이브 문자를 반환합니다.

경로 이름 및 네임스페이스에 대한 자세한 내용은 이름 지정 파일, 경로 및 네임스페이스를 참조하세요.

로컬 경로와 원격 경로를 모두 지정할 수 있습니다. 로컬 경로를 지정하는 경우 GetVolumePathName 은 접두사를 볼륨을 나타내는 가장 긴 접두사인 전체 경로를 반환합니다.

네트워크 공유가 지정된 경우 GetVolumePathName 은 GetDriveType 이 DRIVE_REMOTE 반환하는 가장 짧은 경로를 반환합니다. 즉, 경로가 현재 사용자가 액세스할 수 있는 원격 드라이브로 유효성을 검사합니다.

후행 백슬래시를 반환하지 않는 특정 특수 사례가 있습니다. 출력 버퍼 길이가 한 문자가 너무 짧을 때 발생합니다. 예를 들어 lpszFileName이 이 C: 고 lpszVolumePathName이 4자인 경우 반환되는 값은 이지만 C:\lpszVolumePathName이 3자인 경우 반환되는 값은 입니다C:. 반환 버퍼의 크기를 설정하는 더 안전하지만 느린 방법은 GetFullPathName 함수를 호출한 다음 버퍼 크기가 GetFullPathName 에서 반환하는 전체 경로와 적어도 동일한 크기인지 확인하는 것입니다. 출력 버퍼가 너무 짧은 문자가 두 개 이상이면 함수가 실패하고 오류가 반환됩니다.

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

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

SMB는 볼륨 관리 기능을 지원하지 않습니다.

후행 경로 요소

잘못된 후행 경로 요소는 무시됩니다. 원격 경로의 경우 다음 조건 중 하나가 true이면 전체 경로(후행 요소뿐만 아니라)가 유효하지 않은 것으로 간주됩니다.

경로가 올바르게 구성되지 않았습니다.
경로가 없습니다.
현재 사용자에게 경로에 대한 액세스 권한이 없습니다.

접합 지점 및 탑재된 폴더

지정된 경로가 접합 지점을 트래버스하는 경우 GetVolumePathName 은 접합점이 참조하는 볼륨을 반환합니다. 예를 들어 가 를 가리키는 C:\Adir접합점인 경우 W:\Adir 에 호출된 GetVolumePathName은 를 W:\Adir\Afile 반환합니다C:\. 지정된 경로가 여러 접합 지점을 트래버스하는 경우 전체 체인이 수행되고 GetVolumePathName 은 체인의 마지막 접합점이 참조하는 볼륨을 반환합니다.

탑재된 폴더 또는 접합점에 대한 원격 경로를 지정하면 경로가 원격 경로로 구문 분석되고 탑재된 폴더 또는 접합 지점이 무시됩니다. 예를 들어 가 에 연결 D:\Dir_D 되고 C: 원격 컴퓨터에서 에 매핑 X: 되는 경우 C:\Dir_CGetVolumePathName을 호출하고 원격 컴퓨터에서 를 지정하면 X:\Dir_C 가 반환됩니다X:\.

예제

다음 예제 집합의 경우 U:는 원격 컴퓨터에 \\_YourComputer_\C$매핑되고 Q는 로컬 드라이브입니다.

지정된 경로	함수가 반환됩니다.
`\\_YourComputer_\C$\Windows`	`\\_YourComputer_\C$\`
`\\?\UNC\_YourComputer_\C$\Windows`	`\\?\UNC\_YourComputer_\C$\`
`Q:\Windows`	`Q:\`
`\\?\Q:\Windows`	`\\?\Q:\`
`\\.\Q:\Windows`	`\\.\Q:\`
`\\?\UNC\W:\Windows`	지정된 원격 경로가 유효하지 않아 오류 123이 있는 FALSE입니다. W$ 공유가 없거나 사용자 액세스 권한이 부여되지 않았습니다.
`C:\COM2` (존재)	`\\.\COM2\`
`C:\COM3` (존재하지 않음)	존재하지 않는 COM 디바이스가 지정되었기 때문에 오류 123이 있는 FALSE입니다.

다음 예제 집합의 경우 경로에 잘못된 후행 경로 요소가 포함됩니다.

지정된 경로	함수가 반환됩니다.
`G:\invalid` (잘못된 경로)	`G:\`
`\\.\I:\aaa\invalid` (잘못된 경로)	`\\.\I:\`
`\\_YourComputer_\C$\invalid` (잘못된 후행 경로 요소)	`\\_YourComputer_\C$\`

요구 사항

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

다음을 통해 공유