ホーム › Storage.FileSystem › GetFinalPathNameByHandleW

GetFinalPathNameByHandleW

関数

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

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

シグネチャ

// KERNEL32.dll  (Unicode / -W)
#include <windows.h>

DWORD GetFinalPathNameByHandleW(
    HANDLE hFile,
    LPWSTR lpszFilePath,
    DWORD cchFilePath,
    GETFINALPATHNAMEBYHANDLE_FLAGS dwFlags
);

パラメーター

名前

型

方向

説明

hFile

HANDLE

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

lpszFilePath

LPWSTR

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	NT デバイスオブジェクトのパスを返します。

戻り値の型: DWORD

公式ドキュメント

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

戻り値

関数が成功した場合、戻り値は lpszFilePath が受け取った文字列の長さ(TCHAR 単位)です。この値には終端の NULL 文字のサイズは含まれません。

Windows Server 2008 および Windows Vista: この関数の ANSI 版である GetFinalPathNameByHandleA では、戻り値に終端の NULL 文字のサイズが含まれます。

lpszFilePath が文字列と終端の NULL 文字を格納するには小さすぎるために関数が失敗した場合、戻り値は必要なバッファサイズ(TCHAR 単位)です。この値には終端の NULL 文字のサイズが含まれます。

それ以外の理由で関数が失敗した場合、戻り値はゼロです。拡張エラー情報を取得するには、 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 フラグとともにこの関数に渡して呼び出すと、関数はパスを各構成要素に分割し、それぞれの構成要素について順番に正規化された名前のクエリを試みます。ユーザーがこれらの構成要素のいずれかへのアクセス許可を持っていない場合、関数呼び出しは ERROR_ACCESS_DENIED で失敗します。

最終パスとは、パスが完全に解決されたときに返されるパスです。たとえば、"D:\yourdir" を指す "C:\tmp\mydir" という名前のシンボリックリンクの場合、最終パスは "D:\yourdir" となります。

VOLUME_NAME_DOS を使用する場合、この関数が返す文字列は "\\?\" 構文を使用します。詳細については、CreateFile を参照してください。

VOLUME_NAME_GUID を使用する場合、返されるパスは "\\?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\" のような形式のボリューム GUID パスで始まります。

VOLUME_NAME_NT を使用する場合、返されるパスは NT デバイスオブジェクトのパスであり、"\Device\HarddiskVolume1\" のようなデバイス名で始まります。この種類のパスは相対パスに似ているため、Windows プログラムから直接使用することはできません。

一部のサードパーティ製ドライバーは、Mount Manager を使用せずにドライブ文字またはマウントポイントを作成することがあります。ドライブの作成に Mount Manager が使用されなかった場合、VOLUME_NAME_DOS または VOLUME_NAME_GUID は成功せず、VOLUME_NAME_NT のみが利用可能になります。ボリュームデバイスパスのドライブ文字を特定するには、一致するデバイス名が見つかるまで、すべてのドライブ文字に対して QueryDosDevice 関数を使用します。

Windows 8 および Windows Server 2012 では、この関数は次のテクノロジによってサポートされています。

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

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

各言語での呼び出し定義

// KERNEL32.dll  (Unicode / -W)
#include <windows.h>

DWORD GetFinalPathNameByHandleW(
    HANDLE hFile,
    LPWSTR lpszFilePath,
    DWORD cchFilePath,
    GETFINALPATHNAMEBYHANDLE_FLAGS dwFlags
);

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

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

' hFile : HANDLE
' lpszFilePath : LPWSTR out
' cchFilePath : DWORD
' dwFlags : GETFINALPATHNAMEBYHANDLE_FLAGS
Declare PtrSafe Function GetFinalPathNameByHandleW Lib "kernel32" ( _
    ByVal hFile As LongPtr, _
    ByVal lpszFilePath As LongPtr, _
    ByVal cchFilePath As Long, _
    ByVal dwFlags As Long) As Long
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

GetFinalPathNameByHandleW = ctypes.windll.kernel32.GetFinalPathNameByHandleW
GetFinalPathNameByHandleW.restype = wintypes.DWORD
GetFinalPathNameByHandleW.argtypes = [
    wintypes.HANDLE,  # hFile : HANDLE
    wintypes.LPWSTR,  # lpszFilePath : LPWSTR 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')
GetFinalPathNameByHandleW = Fiddle::Function.new(
  lib['GetFinalPathNameByHandleW'],
  [
    Fiddle::TYPE_VOIDP,  # hFile : HANDLE
    Fiddle::TYPE_VOIDP,  # lpszFilePath : LPWSTR out
    -Fiddle::TYPE_INT,  # cchFilePath : DWORD
    -Fiddle::TYPE_INT,  # dwFlags : GETFINALPATHNAMEBYHANDLE_FLAGS
  ],
  -Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "kernel32")]
extern "system" {
    fn GetFinalPathNameByHandleW(
        hFile: *mut core::ffi::c_void,  // HANDLE
        lpszFilePath: *mut u16,  // LPWSTR 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.Unicode, SetLastError = true)]
public static extern uint GetFinalPathNameByHandleW(IntPtr hFile, [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder lpszFilePath, uint cchFilePath, uint dwFlags);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_GetFinalPathNameByHandleW' -Namespace Win32 -PassThru
# $api::GetFinalPathNameByHandleW(hFile, lpszFilePath, cchFilePath, dwFlags)

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

出力引数:

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