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

반환할 결과의 형식입니다. 이 매개 변수는 다음 값 중 하나일 수 있습니다.

값 의미
FILE_NAME_NORMALIZED
0x0
 정규화된 드라이브 이름을 반환합니다. 기본값입니다.
FILE_NAME_OPENED
0x8
 열린 파일 이름(정규화되지 않음)을 반환합니다.
 

이 매개 변수는 다음 값 중 하나를 포함할 수도 있습니다.

값 의미
VOLUME_NAME_DOS
0x0
 드라이브 문자가 있는 경로를 반환합니다. 기본값입니다.
VOLUME_NAME_GUID
0x1
 드라이브 이름 대신 볼륨 GUID 경로가 있는 경로를 반환합니다.
VOLUME_NAME_NONE
0x4
 드라이브 정보가 없는 경로를 반환합니다.
VOLUME_NAME_NT
0x2
 볼륨 디바이스 경로를 사용하여 경로를 반환합니다.

반환 값

함수가 성공하면 반환 값은 TCHARlpszFilePath받은 문자열의 길이입니다. 이 값에는 종료 null 문자의 크기가 포함되지 않습니다.

Windows Server 2008 및 Windows Vista: 이 함수의 ANSI 버전인 경우 GetFinalPathNameByHandleA반환 값에는 종료 null 문자의 크기가 포함됩니다.

lpszFilePath 너무 작아서 문자열과 종료 null 문자를 보유할 수 없기 때문에 함수가 실패하는 경우 반환 값은 TCHAR필수 버퍼 크기입니다. 이 값에는 종료 null 문자의 크기가 포함됩니다.

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

반환 코드 묘사
ERROR_PATH_NOT_FOUND
 드라이브 문자를 검색하는 중이고 드라이브 문자가 없는 경우 반환할 수 있습니다. 예를 들어 핸들이 현재 탑재되지 않은 드라이브에서 열렸거나 볼륨을 만들고 드라이브 문자를 할당하지 않는 경우입니다. 볼륨에 드라이브 문자가 없는 경우 볼륨 GUID 경로를 사용하여 식별할 수 있습니다.

네트워크 공유에서 볼륨 GUID 경로를 검색하는 경우에도 이 반환 값을 반환할 수 있습니다. 볼륨 GUID 경로는 네트워크 공유에 대해 만들어지지 않습니다.
ERROR_NOT_ENOUGH_MEMORY
 메모리가 부족하여 작업을 완료할 수 없습니다.
ERROR_INVALID_PARAMETER
 dwFlags잘못된 플래그가 지정되었습니다.

발언

SMB(서버 메시지 블록) 프로토콜은 정규화된 경로에 대한 쿼리를 지원하지 않습니다. 따라서 SMB를 사용하여 연 파일의 핸들을 전달하고 FILE_NAME_NORMALIZED 플래그를 사용하여 이 함수를 호출하면 함수는 경로를 해당 구성 요소로 분할하고 각 구성 요소의 정규화된 이름을 쿼리하려고 합니다. 사용자가 해당 구성 요소 중 하나에 대한 액세스 권한이 없는 경우 ERROR_ACCESS_DENIED 함수 호출이 실패합니다.

메모

Windows 10 버전 1709 이상 및 Windows Server 버전 1709 이상은 SMB를 통해 FileNormalizedNameInformation 정보 클래스를 지원합니다. 자세한 내용은 [MS-SMB2 사양](/openspecs/windows_protocols/ms-smb2/a64e55aa-1152-48e4-8206-edd96444e7f7#Appendix_A_414) 부록 A, 섹션 3.3.5.20.1을 참조하세요.

마지막 경로는 경로가 완전히 해결될 때 반환되는 경로입니다. 예를 들어 "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

참고 항목

파일 관리 함수

  • Last updated on