GetFinalPathNameByHandleA 함수(fileapi.h)
지정된 파일의 최종 경로를 검색합니다.
파일 및 경로 이름에 대한 자세한 내용은 파일이름 지정을 참조하세요.
통사론
DWORD GetFinalPathNameByHandleA(
[in] HANDLE hFile,
[out] LPSTR lpszFilePath,
[in] DWORD cchFilePath,
[in] DWORD dwFlags
);
매개 변수
[in] hFile
파일 또는 디렉터리에 대한 핸들입니다.
[out] lpszFilePath
hFile경로를 수신하는 버퍼에 대한 포인터입니다.
[in] cchFilePath
TCHARlpszFilePath크기입니다. 이 값에는 NULL 종료 문자가 포함되어야 합니다.
[in] dwFlags
반환할 결과의 형식입니다. 이 매개 변수는 다음 값 중 하나일 수 있습니다.
| 값 | 의미 |
|---|---|
|
정규화된 드라이브 이름을 반환합니다. 기본값입니다. |
|
열린 파일 이름(정규화되지 않음)을 반환합니다. |
이 매개 변수는 다음 값 중 하나를 포함할 수도 있습니다.
반환 값
함수가 성공하면 반환 값은 TCHARlpszFilePath받은 문자열의 길이입니다. 이 값에는 종료 null 문자의 크기가 포함되지 않습니다.
다른 이유로 인해 함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 얻으려면 GetLastError호출합니다.
| 반환 코드 | 묘사 |
|---|---|
|
드라이브 문자를 검색하는 중이고 드라이브 문자가 없는 경우 반환할 수 있습니다. 예를 들어 핸들이 현재 탑재되지 않은 드라이브에서 열렸거나 볼륨을 만들고 드라이브 문자를 할당하지 않는 경우입니다. 볼륨에 드라이브 문자가 없는 경우 볼륨 GUID 경로를 사용하여 식별할 수 있습니다.
네트워크 공유에서 볼륨 GUID 경로를 검색하는 경우에도 이 반환 값을 반환할 수 있습니다. 볼륨 GUID 경로는 네트워크 공유에 대해 만들어지지 않습니다. |
|
메모리가 부족하여 작업을 완료할 수 없습니다. |
|
dwFlags잘못된 플래그가 지정되었습니다. |
발언
SMB(서버 메시지 블록) 프로토콜은 정규화된 경로에 대한 쿼리를 지원하지 않습니다. 따라서 SMB를 사용하여 연 파일의 핸들을 전달하고 FILE_NAME_NORMALIZED 플래그를 사용하여 이 함수를 호출하면 함수는 경로를 해당 구성 요소로 분할하고 각 구성 요소의 정규화된 이름을 쿼리하려고 합니다. 사용자가 해당 구성 요소 중 하나에 대한 액세스 권한이 없는 경우 ERROR_ACCESS_DENIED 함수 호출이 실패합니다.
마지막 경로는 경로가 완전히 해결될 때 반환되는 경로입니다. 예를 들어 "D:\yourdir"을 가리키는 "C:\tmp\mydir"라는 기호 링크의 경우 마지막 경로는 "D:\yourdir"입니다.
이 함수에서 반환되는 문자열은 "\\?\" 구문을 사용합니다. 자세한 내용은 CreateFile
Windows 8 및 Windows Server 2012에서 이 함수는 다음 기술에서 지원됩니다.
| 기술 | 지원 |
|---|---|
| SMB(서버 메시지 블록) 3.0 프로토콜 | 예 |
| SMB 3.0 TFO(투명한 장애 조치(failover) | 예 |
| SO(스케일 아웃 파일 공유)가 있는 SMB 3.0 | 예 |
| CsvFS(클러스터 공유 볼륨 파일 시스템) | 예 |
| ReFS(복원 파일 시스템) | 예 |
예제
다음 예제에서는 GetFinalPathNameByHandle 함수를 사용하는 방법을 보여 줍니다.
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#define BUFSIZE MAX_PATH
void __cdecl _tmain(int argc, TCHAR *argv[])
{
TCHAR Path[BUFSIZE];
HANDLE hFile;
DWORD dwRet;
printf("\n");
if( argc != 2 )
{
printf("ERROR:\tIncorrect number of arguments\n\n");
printf("%s <file_name>\n", argv[0]);
return;
}
hFile = CreateFile(argv[1], // file to open
GENERIC_READ, // open for reading
FILE_SHARE_READ, // share for reading
NULL, // default security
OPEN_EXISTING, // existing file only
FILE_ATTRIBUTE_NORMAL, // normal file
NULL); // no attr. template
if( hFile == INVALID_HANDLE_VALUE)
{
printf("Could not open file (error %d\n)", GetLastError());
return;
}
dwRet = GetFinalPathNameByHandle( hFile, Path, BUFSIZE, VOLUME_NAME_NT );
if(dwRet < BUFSIZE)
{
_tprintf(TEXT("\nThe final path is: %s\n"), Path);
}
else printf("\nThe required buffer size is %d.\n", dwRet);
CloseHandle(hFile);
}
메모
fileapi.h 헤더는 GETFinalPathNameByHandle을 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입대한
요구 사항
| 요구 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows Vista [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2008 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | fileapi.h(Windows.h 포함) |
| 라이브러리 | Kernel32.lib |
| DLL | Kernel32.dll |