SHAnsiToUnicode 函式 (shlwapi.h)

發行項
03/02/2024

[此函式可透過 Windows XP 和 Windows Server 2003 取得。後續版本的 Windows 中可能會變更或無法使用。

將字串從 ANSI 代碼頁轉換為 Unicode 代碼頁。

語法

int SHAnsiToUnicode(
  [in]  PCSTR pszSrc,
  [out] PWSTR pwszDst,
        int   cwchBuf
);

參數

[in] pszSrc

類型： PCSTR

要轉換成 Unicode 之 Null 終止 ANSI 字串的指標。

[out] pwszDst

類型： PWSTR

緩衝區的指標，當此函式成功傳回時，會在 ANSI 字元轉換為 Unicode (WCHAR) 之後接收 pszSrc 指定的字串。緩衝區必須夠大，才能包含 cwchBuf 參數所指定的 Unicode 字元數目，包括終止的 Null 字元。

cwchBuf

類型： int

pwszDst 所指向之緩衝區可包含的 Unicode 字元數目。這個參數必須大於零。

傳回值

類型： int

傳回寫入 pwszDst 的 Unicode 字元數目，包括終止的 Null 字元。如果失敗，則傳回 0。

備註

安全性警告： 使用此函式不正確可能會危害應用程式的安全性。例如，如果 pwszDst 緩衝區不夠大，無法包含 cwchBuf 指定的字元數，可能會發生緩衝區滿溢。如果發生存取違規，緩衝區滿溢可能會對應用程式造成拒絕服務攻擊。在最糟的情況下，緩衝區滿溢可能會讓攻擊者將可執行的程式代碼插入進程，特別是 pwszDst 是堆棧式緩衝區時。複製整個字串時，請注意 sizeof 會傳回位元組數目，這不是 用於 cwchBuf 參數的正確值。請改用 sizeof (pwszDst) /sizeof (WCHAR) 。請注意，這項技術假設 pwszDst 是陣列，而不是指標。

如果 pwszDst 緩衝區不夠大，無法包含整個轉換的輸出字串，則會截斷字串以符合緩衝區。無法偵測傳回字串已被截斷。字串一律會以 Null 終止，即使已截斷也一樣。這可確保不會超過 cwchBuf 字元複製到 pwszDst。不會嘗試避免截斷 Unicode 代理字組中間的字串。

如果 pszSrc 和 pwszDst 緩衝區重疊，則未定義函式的行為。

注意請勿假設函式尚未變更輸出緩衝區中緊接字串終止 Null 字元的任何字元。字串終止 Null 字元後面的輸出緩衝區內容是未定義的，最多包含緩衝區中的最後一個字元。

SHAnsiToTChar 定義為與 SHAnsiToUnicode 相同。

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional、Windows XP [僅限桌面應用程式]
最低支援的伺服器	Windows 2000 Server、Windows Server 2003 [僅限桌面應用程式]
目標平台	Windows
標頭	shlwapi.h
Dll	Shlwapi.dll (5.0 版或更新版本)