getShortPathNameA 函式 (winbase.h)

發行項
03/13/2024

擷取指定路徑的簡短路徑形式。

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

語法

DWORD GetShortPathNameA(
  [in]  LPCSTR lpszLongPath,
  [out] LPSTR  lpszShortPath,
  [in]  DWORD  cchBuffer
);

參數

[in] lpszLongPath

路徑字串。

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

提示

從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需在前面加上 “\\？\”。如需詳細資訊，請參閱命名檔案、路徑和命名空間的一節。

[out] lpszShortPath

緩衝區的指標，用來接收 lpszLongPath 所指定之路徑的 Null 終止簡短形式。

針對此參數傳遞 NULL ， 而 cchBuffer 的零一律會傳回指定 lpszLongPath 所需的緩衝區大小。

[in] cchBuffer

lpszShortPath 在 TCHAR 中指向的緩衝區大小。

如果 lpszShortPath 設定為 NULL，請將此參數設定為零。

傳回值

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

如果 lpszShortPath 緩衝區太小而無法包含路徑，則傳回值是緩衝區的大小，在 TCHAR 中，這是保存路徑和終止 Null 字元所需的大小。

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

備註

lpszLongPath 參數所指定的路徑不一定是完整或完整路徑。簡短表單可以比指定的路徑長。

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

注意雖然此案例中的傳回值是包含終止 Null 字元的長度，但成功時的傳回值不包含計數中的終止 Null 字元。

如果指定的路徑已經是簡短格式，而且不需要轉換，則函式只會將指定的路徑複製到 lpszShortPath 參數所指定的緩衝區。

您可以將 lpszShortPath 參數設定為與 lpszLongPath 參數相同的值;換句話說，您可以將簡短路徑的輸出緩衝區設定為輸入路徑字串的位址。請務必確定 cchBuffer 參數正確地代表這個 緩衝區的總大小。

您可以藉由呼叫 GetLongPathName 函式，從簡短名稱取得檔案的完整名稱。或者，如果 無法使用 GetLongPathName ，您可以在路徑的每個元件上呼叫 FindFirstFile ，以取得對應的完整名稱。

您可以存取檔案或目錄，但無法存取該檔案或目錄的某些父目錄。因此， 當 GetShortPathName 無法查詢路徑元件的父目錄來判斷該元件的簡短名稱時，可能會失敗。對於已符合簡短名稱需求的目錄元件，可以略過這項檢查。如需詳細資訊，請參閱命名檔案、路徑和命名空間的簡短與長名稱一節。

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

技術	支援
伺服器消息塊 (SMB) 3.0 通訊協定	Yes
SMB 3.0 透明故障轉移 (TFO)	No
具有向外延展檔案共用的SMB 3.0 (SO)	No
叢集共用磁碟區文件系統 (CsvFS)	No
彈性檔案系統 (ReFS)	Yes

SMB 3.0 不支援具有持續可用性功能的共用上的簡短名稱。

復原檔案系統 (ReFS) 不支援簡短名稱。如果您在沒有磁碟上任何簡短名稱的路徑上呼叫 GetShortPathName ，則呼叫將會成功，但會改為傳回長名稱路徑。 NTFS 磁碟區也可能會有此結果，因為不保證指定的完整名稱會有簡短名稱存在。

範例

如需使用 GetShortPathName 的範例，請參閱 GetFullPathName 的範例程式代碼一節。

下列 C++ 範例示範如何使用動態配置的輸出緩衝區。

//...
    long     length = 0;
    TCHAR*   buffer = NULL;

// First obtain the size needed by passing NULL and 0.

    length = GetShortPathName(lpszPath, NULL, 0);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

// Dynamically allocate the correct size 
// (terminating null char was included in length)

    buffer = new TCHAR[length];

// Now simply call again using same long path.

    length = GetShortPathName(lpszPath, buffer, length);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

    _tprintf(TEXT("long name = %s shortname = %s"), lpszPath, buffer);
    
    delete [] buffer;
///...

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限桌面應用程式]
目標平台	Windows
標頭	winbase.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll