GetFinalPathNameByHandleA 함수(fileapi.h)

  • 아티클

지정된 파일의 최종 경로를 검색합니다.

파일 및 경로 이름에 대한 자세한 내용은 파일 이름 지정을 참조하세요.

구문

DWORD GetFinalPathNameByHandleA(
  [in]  HANDLE hFile,
  [out] LPSTR  lpszFilePath,
  [in]  DWORD  cchFilePath,
  [in]  DWORD  dwFlags
);

매개 변수

[in] hFile

파일 또는 디렉터리에 대한 핸들입니다.

[out] lpszFilePath

hFile의 경로를 수신하는 버퍼에 대한 포인터입니다.

[in] cchFilePath

TCHAR의 lpszFilePath 크기입니다. 이 값에는 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
 볼륨 디바이스 경로가 있는 경로를 반환합니다.

반환 값

함수가 성공하면 반환 값은 TCHAR의 lpszFilePath에서 받은 문자열의 길이입니다. 이 값에는 종료 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 함수 호출이 실패합니다.

최종 경로는 경로가 완전히 확인될 때 반환되는 경로입니다. 예를 들어 "D:\yourdir"을 가리키는 "C:\tmp\mydir"라는 기호 링크의 경우 최종 경로는 "D:\yourdir"입니다.

이 함수에서 반환되는 문자열은 "\\?\" 구문을 사용합니다. 자세한 내용은 CreateFile을 참조하세요.

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

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

예제

다음 예제에서는 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

참고 항목

파일 관리 함수