SHUnicodeToAnsi 函式 (shlwapi.h)

發行項
03/02/2024

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

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

語法

int SHUnicodeToAnsi(
  [in]  PCWSTR pwszSrc,
  [out] PSTR   pszDst,
        int    cchBuf
);

參數

[in] pwszSrc

類型： PCWSTR

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

[out] pszDst

類型： PSTR

緩衝區的指標，當此函式成功傳回時，會收到轉換的字元。緩衝區必須夠大，才能包含 cchBuf 參數所指定的 CHAR 字元數目，包括終止 Null 字元的空間。

cchBuf

類型： int

pszDst 所指向之緩衝區可包含的 CHAR 值數目。指派給參數的值必須大於零。

傳回值

類型： int

傳回寫入輸出緩衝區的 CHAR 值數目，包括終止的 Null 字元。如果失敗，則傳回 0。

備註

安全性警告： 使用此函式不正確可能會危害應用程式的安全性。例如，如果 pszDst 緩衝區不夠大，無法包含 cchBuf 指定的字元數，就會發生緩衝區滿溢。如果發生存取違規，緩衝區滿溢可能會對應用程式造成拒絕服務攻擊。在最糟的情況下，緩衝區滿溢可能會讓攻擊者將可執行的程式代碼插入您的進程，特別是 pszDst 是堆棧式緩衝區時。此外，如果輸出字串對緩衝區太大，則會以無訊息方式截斷。這可能會造成標準化或其他安全性弱點。

如果 pszDst 緩衝區不夠大，無法包含整個轉換的輸出字串，則會截斷字串以符合緩衝區。無法偵測傳回字串已被截斷。即使字串已被截斷，字串一律會以 Null 終止。此函式會小心不要在 DBCS 字元組的前置和尾端位元組之間截斷。在此情況下，只會傳回 cchBuf-1 個字元。

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

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

SHTCharToAnsi 定義為與 SHUnicodeToAnsi 相同。

規格需求

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