ホーム › Storage.FileSystem › GetFinalPathNameByHandleA

GetFinalPathNameByHandleA

関数

ファイルハンドルから最終的なパス名を取得する(ANSI版)。

DLLKERNEL32.dll文字セットANSI (-A)呼出規約winapiSetLastErrorあり対応OSWindows Vista 以降

シグネチャ

// KERNEL32.dll  (ANSI / -A)
#include <windows.h>

DWORD GetFinalPathNameByHandleA(
    HANDLE hFile,
    LPSTR lpszFilePath,
    DWORD cchFilePath,
    GETFINALPATHNAMEBYHANDLE_FLAGS dwFlags
);

パラメーター

名前

型

方向

説明

hFile

HANDLE

ファイルまたはディレクトリへのハンドル。

lpszFilePath

LPSTR

out

hFile のパスを受け取るバッファへのポインター。

cchFilePath

DWORD

lpszFilePath のサイズ(TCHAR 単位)。この値には NULL 終端文字を含める必要があります。

dwFlags

GETFINALPATHNAMEBYHANDLE_FLAGS

返す結果の種類。このパラメーターには、次のいずれかの値を指定できます。

値	意味
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	ボリュームデバイスパスを含むパスを返します。

戻り値の型: DWORD

公式ドキュメント

指定したファイルの最終パスを取得します。(ANSI)

戻り値

関数が成功した場合、戻り値は lpszFilePath が受け取った文字列の長さ(TCHAR 単位)です。この値には終端の 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 に無効なフラグが指定されました。

解説(Remarks)

Server Message Block (SMB) プロトコルは、正規化されたパスのクエリをサポートしていません。そのため、SMB を使用して開いたファイルのハンドルを FILE_NAME_NORMALIZED フラグとともに指定してこの関数を呼び出すと、関数はパスをその構成要素に分割し、それぞれの構成要素の正規化された名前を順にクエリしようとします。それらの構成要素のいずれか 1 つに対してユーザーがアクセス許可を持っていない場合、関数呼び出しは ERROR_ACCESS_DENIED で失敗します。

メモ

Windows 10 バージョン 1709 以降および Windows Server バージョン 1709 以降では、SMB 経由で FileNormalizedNameInformation 情報クラスがサポートされます。詳細については、[MS-SMB2 specification] (/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 では、この関数は次のテクノロジでサポートされています。

テクノロジ	サポート
Server Message Block (SMB) 3.0 プロトコル	はい
SMB 3.0 透過的フェールオーバー (TFO)	はい
SMB 3.0 スケールアウトファイル共有 (SO)	はい
クラスター共有ボリュームファイルシステム (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 を、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI バージョンまたは Unicode バージョンを自動的に選択するエイリアスとして定義しています。エンコーディング非依存のエイリアスを、エンコーディング非依存でないコードと混在して使用すると、不一致が生じてコンパイルエラーまたは実行時エラーにつながる可能性があります。詳細については、Conventions for Function Prototypes を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// KERNEL32.dll  (ANSI / -A)
#include <windows.h>

DWORD GetFinalPathNameByHandleA(
    HANDLE hFile,
    LPSTR lpszFilePath,
    DWORD cchFilePath,
    GETFINALPATHNAMEBYHANDLE_FLAGS dwFlags
);

[DllImport("KERNEL32.dll", CharSet = CharSet.Ansi, SetLastError = true, ExactSpelling = true)]
static extern uint GetFinalPathNameByHandleA(
    IntPtr hFile,   // HANDLE
    [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder lpszFilePath,   // LPSTR out
    uint cchFilePath,   // DWORD
    uint dwFlags   // GETFINALPATHNAMEBYHANDLE_FLAGS
);

<DllImport("KERNEL32.dll", CharSet:=CharSet.Ansi, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function GetFinalPathNameByHandleA(
    hFile As IntPtr,   ' HANDLE
    <MarshalAs(UnmanagedType.LPStr)> lpszFilePath As System.Text.StringBuilder,   ' LPSTR out
    cchFilePath As UInteger,   ' DWORD
    dwFlags As UInteger   ' GETFINALPATHNAMEBYHANDLE_FLAGS
) As UInteger
End Function

' hFile : HANDLE
' lpszFilePath : LPSTR out
' cchFilePath : DWORD
' dwFlags : GETFINALPATHNAMEBYHANDLE_FLAGS
Declare PtrSafe Function GetFinalPathNameByHandleA Lib "kernel32" ( _
    ByVal hFile As LongPtr, _
    ByVal lpszFilePath As String, _
    ByVal cchFilePath As Long, _
    ByVal dwFlags As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

GetFinalPathNameByHandleA = ctypes.windll.kernel32.GetFinalPathNameByHandleA
GetFinalPathNameByHandleA.restype = wintypes.DWORD
GetFinalPathNameByHandleA.argtypes = [
    wintypes.HANDLE,  # hFile : HANDLE
    wintypes.LPSTR,  # lpszFilePath : LPSTR out
    wintypes.DWORD,  # cchFilePath : DWORD
    wintypes.DWORD,  # dwFlags : GETFINALPATHNAMEBYHANDLE_FLAGS
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
GetFinalPathNameByHandleA = Fiddle::Function.new(
  lib['GetFinalPathNameByHandleA'],
  [
    Fiddle::TYPE_VOIDP,  # hFile : HANDLE
    Fiddle::TYPE_VOIDP,  # lpszFilePath : LPSTR out
    -Fiddle::TYPE_INT,  # cchFilePath : DWORD
    -Fiddle::TYPE_INT,  # dwFlags : GETFINALPATHNAMEBYHANDLE_FLAGS
  ],
  -Fiddle::TYPE_INT)

#[link(name = "kernel32")]
extern "system" {
    fn GetFinalPathNameByHandleA(
        hFile: *mut core::ffi::c_void,  // HANDLE
        lpszFilePath: *mut u8,  // LPSTR out
        cchFilePath: u32,  // DWORD
        dwFlags: u32  // GETFINALPATHNAMEBYHANDLE_FLAGS
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("KERNEL32.dll", CharSet = CharSet.Ansi, SetLastError = true)]
public static extern uint GetFinalPathNameByHandleA(IntPtr hFile, [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder lpszFilePath, uint cchFilePath, uint dwFlags);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_GetFinalPathNameByHandleA' -Namespace Win32 -PassThru
# $api::GetFinalPathNameByHandleA(hFile, lpszFilePath, cchFilePath, dwFlags)

#uselib "KERNEL32.dll"
#func global GetFinalPathNameByHandleA "GetFinalPathNameByHandleA" sptr, sptr, sptr, sptr
; GetFinalPathNameByHandleA hFile, varptr(lpszFilePath), cchFilePath, dwFlags   ; 戻り値は stat
; hFile : HANDLE -> "sptr"
; lpszFilePath : LPSTR out -> "sptr"
; cchFilePath : DWORD -> "sptr"
; dwFlags : GETFINALPATHNAMEBYHANDLE_FLAGS -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "KERNEL32.dll"
#cfunc global GetFinalPathNameByHandleA "GetFinalPathNameByHandleA" sptr, var, int, int
; res = GetFinalPathNameByHandleA(hFile, lpszFilePath, cchFilePath, dwFlags)
; hFile : HANDLE -> "sptr"
; lpszFilePath : LPSTR out -> "var"
; cchFilePath : DWORD -> "int"
; dwFlags : GETFINALPATHNAMEBYHANDLE_FLAGS -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "KERNEL32.dll"
#cfunc global GetFinalPathNameByHandleA "GetFinalPathNameByHandleA" sptr, sptr, int, int
; res = GetFinalPathNameByHandleA(hFile, varptr(lpszFilePath), cchFilePath, dwFlags)
; hFile : HANDLE -> "sptr"
; lpszFilePath : LPSTR out -> "sptr"
; cchFilePath : DWORD -> "int"
; dwFlags : GETFINALPATHNAMEBYHANDLE_FLAGS -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。