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

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

このパラメーターには、次のいずれかの値を含めることもできます。

戻り値

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

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

lpszFilePath が小さすぎて文字列と終端の null 文字を保持できないために関数が失敗した場合、戻り値は TCHARs で必要なバッファー サイズになります。 この値には、終端の null 文字のサイズが含まれます。

その他の理由で関数が失敗した場合、戻り値は 0 になります。 詳細なエラー情報を得るには、GetLastError を呼び出します。

注釈

サーバー メッセージ ブロック (SMB) プロトコルでは、正規化されたパスのクエリはサポートされていません。 したがって、SMB を使用して開かれたファイルのハンドルを渡し、FILE_NAME_NORMALIZED フラグを指定してこの関数を呼び出すと、関数はパスをそのコンポーネントに分割し、それらの各コンポーネントの正規化された名前を順番に照会しようとします。 ユーザーがこれらのコンポーネントのいずれかに対するアクセス許可を持たない場合、関数呼び出しはERROR_ACCESS_DENIEDで失敗します。

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

この関数によって返される文字列は、"\\?\" 構文を使用します。 詳細については、CreateFile のページを参照してください。

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

例

次の例では、 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);
}

要件

関連項目

File Management 関数