共用方式為

PathAllocCanonicalize 函式 （pathcch.h）

  • 發行項

將路徑字串轉換成標準格式。

此函式不同於 PathCchCanonicalize 和 PathCchCanonicalizeEx，因為它會在堆積上傳回結果。 這表示呼叫端不需要宣告傳回字串的大小並減少堆疊使用。

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

注意 此函式 PathCchCanonicalize或 PathCchCanonicalizeEx，應用來取代 pathCanonicalize 。

語法

WINPATHCCHAPI HRESULT PathAllocCanonicalize(
  [in]  PCWSTR pszPathIn,
  [in]  ULONG  dwFlags,
  [out] PWSTR  *ppszPathOut
);

參數

[in] pszPathIn

包含原始字串之緩衝區的指標。 這個值不能 NULL。

[in] dwFlags

下列一或多個旗標：

價值 意義
PATHCCH_NONE
0x0000000
 不允許建構比 MAX_PATH 長的路徑（即長路徑）。
PATHCCH_ALLOW_LONG_PATHS
0x00000001
 允許建置長度超過 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 開始提供。
PATHCCH_CANONICALIZE_SLASHES
0x00000040
 將正斜線轉換為反斜線，並折疊多個斜線。

附注 此值可從 Windows 11 開始提供（SDK 10.0.22000.194 版）。

[out] ppszPathOut

成功傳回此函式時，緩衝區指標的位址會接收標準路徑字串。 呼叫者必須藉由呼叫 localFree 函式來釋放此資源，而不再需要資源。 這個值不能 NULL。

傳回值

如果函式成功，則會傳回 S_OK。 否則，它會傳回 HRESULT 錯誤碼。

言論

這個函式支援這些替代路徑表單：

  • \\?\
  • \\？\\UNC\
  • \\？\Volume{guid}\

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

要求

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