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

戻り値

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

Windows Server 2008 と Windows Vista: この関数の ANSI バージョン である GetFinalPathNameByHandleA の場合、戻り値には終端の null 文字のサイズが含まれます。

lpszFilePath が小さすぎて文字列と終端の null 文字を保持できないために関数が失敗した場合、戻り値は TCHARs で必要なバッファー サイズになります。 この値には、終端の 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 プロトコル はい
SMB 3.0 Transparent Failover (TFO) はい
スケールアウト ファイル共有 (SO) を使う SMB 3.0 はい
クラスターの共有ボリューム ファイル システム (CsvFS) はい
Resilient File System (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 を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ | UWP アプリ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリ | UWP アプリ]
対象プラットフォーム Windows
ヘッダー fileapi.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

File Management 関数