共用方式為

PathCchCanonicalizeEx 函式 (pathcch.h)

  • 發行項

藉由移除 「.」 和 「.」 等導覽元素來產生直接、格式正確的路徑，以簡化路徑。

此函式與 PathCchCanonicalize 不同，因為它允許建構較長的最終路徑。

此函式與 PathAllocCanonicalize 不同，表示呼叫端必須宣告傳回字串的大小，儲存在堆疊上。

此函式與 PathCanonicalize 不同，因為它接受具有 “\”、“\？” 和 “\？\UNC” 前置詞的路徑。

注意 此函式 PathCchCanonicalize 或 PathAllocCanonicalize 應該用來取代 PathCanonicalize ，以防止緩衝區溢出的可能性。

語法

WINPATHCCHAPI HRESULT PathCchCanonicalizeEx(
  [out] PWSTR  pszPathOut,
  [in]  size_t cchPathOut,
  [in]  PCWSTR pszPathIn,
  [in]  ULONG  dwFlags
);

參數

[out] pszPathOut

緩衝區的指標，當此函式成功傳回時，會收到編輯的路徑字串。

[in] cchPathOut

pszPathOut 所指向的緩衝區大小，以字元為單位。

[in] pszPathIn

原始路徑字串的指標。 如果此值為 NULL、指向空字串，或在移除 “.” 和 “..” 元素之後產生空字串，則會將單一反斜杠複製到 pszPathOut 所指向的緩衝區。

[in] dwFlags

下列一或多個旗標：

值 意義
PATHCCH_NONE
0x0000000
 不允許建構 \\？\ 路徑 (亦即，長路徑) 超過 MAX_PATH 。
PATHCCH_ALLOW_LONG_PATHS
0x00000001
 允許建置超過 MAX_PATH 的 \\？\ 路徑。 請注意， cchPathOut 必須大於 MAX_PATH 。 如果不是，則會忽略此旗標。
PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS
0x00000002
 強制 API 將呼叫端視為已啟用長路徑，與進程已啟用長名稱的狀態無關。 只有在指定 PATHCCH_ALLOW_LONG_PATHS 時，才能使用此選項，而且不能與 PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS搭配使用。

注意此值從 Windows 10 1703 版開始提供。
PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS
0x00000004
 強制 API 將呼叫端視為已停用的長路徑，與進程已啟用長名稱的狀態無關。 只有在指定 PATHCCH_ALLOW_LONG_PATHS 時，才能使用此選項，而且不能與 PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS搭配使用。

注意此值從 Windows 10 1703 版開始提供。
PATHCCH_DO_NOT_NORMALIZE_SEGMENTS
0x00000008
 停用路徑區段的正規化，包括移除尾端點和空格。 這可讓您存取 win32 路徑正規化將會封鎖的路徑。

注意此值從 Windows 10 1703 版開始提供。
PATHCCH_ENSURE_IS_EXTENDED_LENGTH_PATH
0x00000010
 將輸入路徑轉換成延伸長度 DOS 裝置路徑表單， (如果尚未在該窗體中，則會使用 \\？\ 前置詞) 。 這可讓存取因 Win32 正規化規則而無法尋址的路徑， (可以移除尾端點和空格) 和路徑長度限制。 此選項表示 PATHCCH_DO_NOT_NORMALIZE_SEGMENTS的相同行為。

注意此值從 Windows 10 1703 版開始提供。
PATHCCH_ENSURE_TRAILING_SLASH
0x00000020
 合併或正規化路徑時，請確定有尾端反斜杠。

注意此值從 Windows 10 1703 版開始提供。

傳回值

如果此函式成功，則會傳回 S_OK。 否則，它會傳回 HRESULT 程式代碼，包括但不限於下列程式代碼。

傳回碼 Description
E_INVALIDARG
 cchPathOut 值大於 PATHCCH_MAX_CCH。
PATHCCH_E_FILENAME_TOO_LONG
 路徑區段具有超過 PATHCCH_MAX_CCH 個字元，或者，如果未設定 PATHCCH_ALLOW_LONG_PATHS 旗標，就會超過標準路徑區段長度限制 256 個字元。
E_OUTOFMEMORY
 函式無法配置必要大小的緩衝區。

備註

此函式會響應路徑中內嵌的字串 “.” 和 “..”。 “..” 字串表示要移除緊接在路徑區段前面的 。 “.” 字串表示要略過下一個路徑區段。 請注意，無法移除路徑的根區段。 如果 “..” 字串比路徑區段還多，則函式會傳回 S_OK ， 而 pszPathOut 所指向的緩衝區包含單一反斜杠 “\”。

除了前面加上 「通配符之外，所有尾端句點都會從路徑中移除。在此情況下，會在 '' 字元之後保留單一句號，但會移除所有其他尾端句點。

如果產生的路徑是根磁碟驅動器 (“x：”) ，則會附加反斜杠 (“x：\”) 。

此函式不會將正斜線 (/) 轉換成反斜線 (\) 。 使用不受信任的輸入時，此函式本身無法用來將路徑轉換成窗體，而該窗體可以與其他子路徑或身分識別的路徑進行比較。 需要該功能的呼叫端應該在使用此函式之前，先將正斜線轉換成反斜線。

下列範例顯示這些字串的效果。

原始字串 標準字串
C：\name_1\.\name_2\..\name_3 C：\name_1\name_3
C：\name_1\..\name_2\.\name_3 C：\name_2\name_3
C：\name_1\name_2\.\name_3\..\name_4 C：\name_1\name_2\name_4
C：\name_1\.\name_2\.\name_3\.。\name_4\.. C：\name_1\name_2
C：\name_1\*... C：\name_1\*。
C：\。。 C:\

規格需求

需求 值
最低支援的用戶端 Windows 8 [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2012 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 pathcch.h
程式庫 Pathcch.lib

另請參閱

PathCchCanonicalize