GetFullPathNameW 函式 （fileapi.h）

擷取指定檔案的完整路徑和檔名。

若要以交易作業的形式執行這項作業，請使用 GetFullPathNameTransacted 函式。

如需檔案和路徑名稱的詳細資訊，請參閱 檔名、路徑和命名空間。

語法

DWORD GetFullPathNameW(
  [in]  LPCWSTR lpFileName,
  [in]  DWORD   nBufferLength,
  [out] LPWSTR  lpBuffer,
  [out] LPWSTR  *lpFilePart
);

參數

[in] lpFileName

檔名。

此參數可以是簡短的 （8.3 窗體） 或長檔名。 此字串也可以是共用或磁碟區名稱。

根據預設，名稱限製為MAX_PATH個字元。 若要將此限制延伸至 32,767 寬字元，請在路徑前面加上 “\\？\”。 如需詳細資訊，請參閱 命名檔案、路徑和命名空間。

[in] nBufferLength

要接收磁碟驅動器和路徑之 null 終止字串的緩衝區大小，TCHAR。

[out] lpBuffer

緩衝區的指標，接收磁碟驅動器和路徑的 Null 終止字串。

[out] lpFilePart

接收路徑中最終檔名元件之位址的緩衝區指標（在 lpBuffer內）。

此參數可以是 NULL。

如果 lpBuffer 參照目錄而非檔案，lpFilePart 會收到零。

傳回值

如果函式成功，傳回值會是複製到 lpBuffer之字串的長度，TCHAR，不包含終止的 null 字元。

如果 lpBuffer 緩衝區太小而無法包含路徑，則傳回值會是大小，以 TCHAR為保留路徑和終止 Null 字元所需的緩衝區。

如果函式因任何其他原因而失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

言論

GetFullPathName 合併目前磁碟驅動器和目錄的名稱與指定的檔名，以判斷指定檔案的完整路徑和檔名。 它也會計算完整路徑和檔名之檔名部分的位址。

此函式不會驗證產生的路徑和檔名是否有效，或它們看到相關聯磁碟區上的現有檔案。

請注意，lpFilePart 參數不需要字元串緩衝區空間，但只足夠用於單一位址。 這是因為它只會在緩衝區內傳回已存在 lpBuffer的位址。

共用和磁碟區名稱是 lpFileName的有效輸入。 例如，如果 test-2 是遠端電腦且 U：是目前目錄為磁碟區根目錄的網路對應磁碟驅動器，下列清單會識別傳回的路徑和檔名：

• 如果您指定 “\\test-2\q$\lh” 傳回的路徑為 “\\test-2\q$\lh”
• 如果您指定 “\\？\UNC\test-2\q$\lh” 傳回的路徑是 “\\？\UNC\test-2\q$\lh”
• 如果您指定 “U：” 傳回的路徑是 “U：\” 磁碟驅動器上的目前目錄

如果傳回值大於或等於 nBufferLength 中所指定的值，您可以使用足以保存路徑的緩衝區再次呼叫 函式。 如需此案例的範例，除了使用零長度緩衝區進行動態配置之外，請參閱範例程式代碼一節。

傳遞至 GetFullPathName 函式的相對路徑會解譯為相對於進程的目前目錄。 SetCurrentDirectory 函式所撰寫的目前目錄狀態是進程的全域狀態，而且可以隨時由任何線程變更。 應用程式應該注意，如果目前目錄在兩個呼叫之間變更，GetFullPathName 函式的連續呼叫可能會產生不同的結果。

為了避免產生不一致的結果所造成的問題，多線程應用程式和共用連結庫程式碼應該避免使用相對路徑。 如果收到相對路徑，則應該只取用一次，方法是將相對路徑直接傳遞至 CreateFile之類的函式，或將它轉換成絕對路徑，並使用該點向前的絕對路徑。

在 Windows 8 和 Windows Server 2012 中，下列技術支援此功能。

例子

下列C++範例示範 GetFullPathName、GetLongPathName和 GetShortPathName的基本用法。 如需使用動態配置的另一個範例，請參閱 GetShortPathName。

#include <windows.h>
#include <tchar.h>
#include <stdio.h>

#define BUFSIZE 4096
#define LONG_DIR_NAME TEXT("c:\\longdirectoryname")

void _tmain(int argc, TCHAR *argv[])
{
    DWORD  retval=0;
    BOOL   success; 
    TCHAR  buffer[BUFSIZE]=TEXT(""); 
    TCHAR  buf[BUFSIZE]=TEXT(""); 
    TCHAR** lppPart={NULL};

   if( argc != 2 )
   {
      _tprintf(TEXT("Usage: %s [file]\n"), argv[0]);
      return;
   }

// Retrieve the full path name for a file. 
// The file does not need to exist.

    retval = GetFullPathName(argv[1],
                 BUFSIZE,
                 buffer,
                 lppPart);
    
    if (retval == 0) 
    {
        // Handle an error condition.
        printf ("GetFullPathName failed (%d)\n", GetLastError());
        return;
    }
    else 
    {
        _tprintf(TEXT("The full path name is:  %s\n"), buffer);
        if (lppPart != NULL && *lppPart != 0)
        {
            _tprintf(TEXT("The final component in the path name is:  %s\n"), *lppPart);
        }
    }


// Create a long directory name for use with the next two examples.

    success = CreateDirectory(LONG_DIR_NAME,
                              NULL);

    if (!success)
    {
        // Handle an error condition.
        printf ("CreateDirectory failed (%d)\n", GetLastError());
        return;
    }


// Retrieve the short path name.  

    retval = GetShortPathName(LONG_DIR_NAME,
                  buf,
                  BUFSIZE);

    if (retval == 0) 
    {
        // Handle an error condition.
         printf ("GetShortPathName failed (%d)\n", GetLastError());
         return;
    }
    else _tprintf(TEXT("The short name for %s is %s\n"), 
                  LONG_DIR_NAME, buf);


// Retrieve the long path name.  

    retval = GetLongPathName(buf,
              buffer,
              BUFSIZE);

    if (retval == 0) 
    {
        // Handle an error condition.
         printf ("GetLongPathName failed (%d)\n", GetLastError());
         return;
    }
    else _tprintf(TEXT("The long name for %s is %s\n"), buf, buffer);

// Clean up the directory.

    success = RemoveDirectory(LONG_DIR_NAME);
    if (!success)
    {
        // Handle an error condition.
        printf ("RemoveDirectory failed (%d)\n", GetLastError());
        return;
    }
}

要求

另請參閱

檔案管理功能

GetFullPathNameTransacted

GetLongPathName

GetShortPathName

GetTempPath

SearchPath