PathCanonicalizeW 函式 (shlwapi.h)

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

注意 誤用此函式可能會導致緩衝區溢出。 我們建議使用更安全的 PathCchCanonicalize 或 PathCchCanonicalizeEx 函式。

 

語法

BOOL PathCanonicalizeW(
  [out] LPWSTR  pszBuf,
  [in]  LPCWSTR pszPath
);

參數

[out] pszBuf

類型： LPTSTR

接收標準路徑之字串的指標。 您必須將此緩衝區的大小設定為MAX_PATH，以確保它夠大，才能保存傳回的字串。

[in] pszPath

類型： LPCTSTR

長度上限為 null 之字串的指標，MAX_PATH包含要標準化的路徑。

傳回值

類型： BOOL

如果已計算結果，且 lpszDst 輸出緩衝區的內容有效，則會傳回 TRUE。 否則會傳回 FALSE ，而 lpszDst 所指向的緩衝區內容無效。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

此函式可讓使用者指定要從路徑中移除的專案，方法是將特殊字元序列插入路徑。 “..” 序列表示從目前位置移除路徑區段到上一個路徑區段。 “.” 序列表示要略過下一個路徑區段到下列路徑區段。 無法移除路徑的根區段。

如果 「..」 序列比路徑區段還多，則函式會傳回 TRUE ，而 lpszDst 指向的緩衝區內容只包含根目錄 “ ”。

範例

#include <windows.h>
#include <iostream>
#include "Shlwapi.h"

using namespace std;

int main( void )
{
// Path_1 destination buffer.
char buffer_1[MAX_PATH] = "JustABufferToHoldTheCanonicalizedPathForAnExample";
char *lpStr1;
lpStr1 = buffer_1;

// Path_2 to be Canonicalized.
char buffer_2[ ] = "A:\\name_1\\.\\name_2\\..\\name_3";
char *lpStr2;
lpStr2 = buffer_2;

// Path_3 to be Canonicalized.
char buffer_3[ ] = "A:\\name_1\\..\\name_2\\.\\name_3";
char *lpStr3;
lpStr3 = buffer_3;

// Path_4 to be Canonicalized.
char buffer_4[ ] = "A:\\name_1\\name_2\\.\\name_3\\..\\name_4";
char *lpStr4;
lpStr4 = buffer_4;

// Path_5 to be Canonicalized.
char buffer_5[ ] = "A:\\name_1\\.\\name_2\\.\\name_3\\..\\name_4\\..";
char *lpStr5;
lpStr5 = buffer_5;

// Path_6 to be Canonicalized.
char buffer_6[ ] = "C:\\..";
char *lpStr6;
lpStr6 = buffer_6;

cout << "The un-canonicalized path 2 is : " << lpStr2
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr2)
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

cout << "\nThe un-canonicalized path 3 is : " << lpStr3
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr3)
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

cout << "\nThe un-canonicalized path 4 is : " << lpStr4
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr4)
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

cout << "\nThe un-canonicalized path 5 is : " << lpStr5
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr5) 
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

cout << "\nThe un-canonicalized path 6 is : " << lpStr6
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr6)
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;
}
OUTPUT:
---------
The un-canonicalized path 2 is : A:\name_1\.\name_2\..\name_3
The return value is            : 1
The canonicalized path 1 is    : A:\name_1\name_3

The un-canonicalized path 3 is : A:\name_1\..\name_2\.\name_3
The return value is            : 1
The canonicalized path 1 is    : A:\name_2\name_3

The un-canonicalized path 4 is : A:\name_1\name_2\.\name_3\..\name_4
The return value is            : 1
The canonicalized path 1 is    : A:\name_1\name_2\name_4

The un-canonicalized path 5 is : A:\name_1\.\name_2\.\name_3\..\name_4\..
The return value is            : 1
The canonicalized path 1 is    : A:\name_1\name_2

The un-canonicalized path 6 is : C:\..
The return value is            : 1
The canonicalized path 1 is    : C:\

注意

shlwapi.h 標頭會將PathCanonicalize定義為別名，根據UNICODE預處理器常數的定義，自動選取此函式的ANSI或Unicode版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版、Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	shlwapi.h
程式庫	Shlwapi.lib
Dll	Shlwapi.dll (4.71 版或更新版本)