WideCharToMultiByte 函式 (stringapiset.h)
將UTF-16 (寬字元) 字串對應至新的字元字串。 新的字元字串不一定來自多位元組字元集。
從UTF-16轉換成非Unicode編碼的數據會受限於數據遺失，因為代碼頁可能無法代表特定 Unicode 資料中使用的每一個字元。 如需詳細資訊，請參閱 安全性考慮：國際功能。
語法
int WideCharToMultiByte(
[in] UINT CodePage,
[in] DWORD dwFlags,
[in] _In_NLS_string_(cchWideChar)LPCWCH lpWideCharStr,
[in] int cchWideChar,
[out, optional] LPSTR lpMultiByteStr,
[in] int cbMultiByte,
[in, optional] LPCCH lpDefaultChar,
[out, optional] LPBOOL lpUsedDefaultChar
);
參數
[in] CodePage
要用於執行轉換的代碼頁。 這個參數可以設定為操作系統中所安裝或可用之任何代碼頁的值。 如需代碼頁的清單，請參閱 代碼頁標識碼。 您的應用程式也可以指定下表所示的其中一個值。
[in] dwFlags
指出轉換類型的旗標。 應用程式可以指定下列值的組合。 當未設定這些旗標時，函式的執行速度會更快。 應用程式應該使用特定值來指定WC_NO_BEST_FIT_CHARS和WC_COMPOSITECHECK，WC_DEFAULTCHAR擷取所有可能的轉換結果。 如果未提供這三個值，部分結果將會遺失。
| 值 | 意義 | ||||||
|---|---|---|---|---|---|---|---|
|
轉換複合字元，由基底字元和非步調字元組成，每個字元各有不同的字元值。 將這些字元轉譯為先行編譯的字元，其具有基底非步調字元組合的單一字元值。 例如，在字元 è 中，e 是基底字元，而輔色符號則是非步調字元。 注意 Windows 通常會代表具有預先編譯數據的 Unicode 字串，因此不需要使用 WC_COMPOSITECHECK 旗標。
您的應用程式可以結合WC_COMPOSITECHECK與下列任何一個旗標，並將預設值WC_SEPCHARS。 當 Unicode 字串中沒有基底非步調字元組合的預先編譯對應時，這些旗標會決定函式的行為。 如果未提供這些旗標，函式的行為就如同已設定WC_SEPCHARS旗標一樣。 For more information, see WC_COMPOSITECHECK and related flags in the Remarks section.
|
||||||
|
Windows Vista 和更新版本： 如果遇到無效的輸入字元，則傳回 0 並將最後一個錯誤碼設定為 ERROR_NO_UNICODE_TRANSLATION) ，以失敗 (。 您可以使用 呼叫 GetLastError 來擷取最後一個錯誤碼。 如果未設定此旗標，函式會以U+FFFD取代不合法的序列， (針對指定的代碼頁編碼) ，並傳回轉換字串的長度來成功。 請注意，只有當 CodePage 指定為 CP_UTF8 或 54936 時，才會套用此旗標。 它不能與其他代碼頁值搭配使用。 | ||||||
|
轉譯任何未直接轉譯為多位元組的 Unicode 字元，相當於 lpDefaultChar 所指定的預設字元。 換句話說，如果從 Unicode 轉譯為多位元組，而再次轉譯回 Unicode 並不會產生相同的 Unicode 字元，則函式會使用預設字元。 這個旗標可以單獨使用，或與其他定義的旗標搭配使用。
對於需要驗證的字串，例如檔案、資源和使用者名稱，應用程式應該一律使用WC_NO_BEST_FIT_CHARS旗標。 此旗標可防止函式將字元對應至看起來類似但語意非常不同的字元。 在某些情況下，語意變更可能非常極端。 例如，某些代碼頁中「∞」 的符號 (無限大) 對應至 8 (8) 。 |
針對下列代碼頁， dwFlags 必須是 0。 否則，函式會因為ERROR_INVALID_FLAGS而失敗。
- 50220
- 50221
- 50222
- 50225
- 50227
- 50229
- 57002 到 57011
- 65000 (UTF-7)
- 42 (符號)
[in] lpWideCharStr
要轉換的 Unicode 字串指標。
[in] cchWideChar
大小，以字元為單位，以 lpWideCharStr 表示的字串。 或者，如果字串為 null 終止，則可以將此參數設定為 -1。 如果 cchWideChar 設定為 0，則函式會失敗。
如果此參數為 -1，函式會處理整個輸入字串，包括終止的 Null 字元。 因此，產生的字元字串具有終止 Null 字元，而函式傳回的長度會包含這個字元。
如果此參數設定為正整數，則函式會完全處理指定的字元數。 如果提供的大小不包含終止 Null 字元，則產生的字元字串不會以 Null 結尾，而且傳回的長度不包含此字元。
[out, optional] lpMultiByteStr
接收已轉換字串之緩衝區的指標。
[in] cbMultiByte
以位元組為單位的緩衝區大小，以位元組為單位，以 lpMultiByteStr 表示。 如果此值為 0，函式會傳回所需的緩衝區大小，以位元組為單位，包括任何終止的 Null 字元，而且不會使用 lpMultiByteStr 緩衝區。
[in, optional] lpDefaultChar
如果指定的代碼頁中無法表示字元，則為要使用的字元指標。 如果函式是使用系統預設值，應用程式會將此參數設定為 NULL 。 若要取得系統預設字元，應用程式可以呼叫 GetCPInfo 或 GetCPInfoEx 函式。
針對 CodePage 的CP_UTF7和CP_UTF8設定，此參數必須設定為 NULL。 否則，函式會因為ERROR_INVALID_PARAMETER而失敗。
[out, optional] lpUsedDefaultChar
旗標的指標，指出函式是否已在轉換中使用預設字元。 如果來源字串中的一或多個字元無法在指定的代碼頁中表示，則旗標會設定為 TRUE 。 否則，旗標會設定為 FALSE。 此參數可以設定為 NULL。
針對 CodePage 的CP_UTF7和CP_UTF8設定，此參數必須設定為 NULL。 否則，函式會因為ERROR_INVALID_PARAMETER而失敗。
傳回值
如果成功，則傳回 寫入至 lpMultiByteStr 所指向之緩衝區的位元元組數目。 如果函式成功且 cbMultiByte 為 0，則傳回值是 lpMultiByteStr 所指示緩衝區所需的大小，以位元組為單位。 另請參閱 dwFlags ，以取得當輸入無效序列時，WC_ERR_INVALID_CHARS旗標如何影響傳回值的相關信息。
如果函式未成功，則傳回 0。 若要取得延伸的錯誤資訊，應用程式可以呼叫 GetLastError，這可以傳回下列其中一個錯誤碼：
- ERROR_INSUFFICIENT_BUFFER。 提供的緩衝區大小不夠大，或設定為 NULL 不正確。
- ERROR_INVALID_FLAGS。 為旗標的值無效。
- ERROR_INVALID_PARAMETER。 任何參數值都無效。
- ERROR_NO_UNICODE_TRANSLATION。 在字串中找到無效的 Unicode。
備註
lpMultiByteStr 和 lpWideCharStr 指標不得相同。 如果它們相同，則函式會失敗，而 GetLastError 會傳回ERROR_INVALID_PARAMETER。
如果明確指定輸入字串長度而不終止 Null 字元，WideCharToMultiByte 不會以 Null 終止輸出字串。 若要以 null 終止此函式的輸出字串，應用程式應該傳入 -1，或明確計算輸入字串的終止 Null 字元。
如果 cbMultiByte 小於 cchWideChar，此函式會將 cbMultiByte 所指定的字元數寫入 lpMultiByteStr 所指示的緩衝區。 不過，如果 CodePage 設定為 CP_SYMBOL，而 cbMultiByte 小於 cchWideChar， 則函式不會將任何字元寫入 lpMultiByteStr。
當 lpDefaultChar 和 lpUsedDefaultChar 都設定為 NULL 時，WideCharToMultiByte 函式最有效率地運作。 下表顯示這些參數四種可能組合之函式的行為。
| lpDefaultChar | lpUsedDefaultChar | 結果 |
|---|---|---|
| NULL | NULL | 沒有預設檢查。 這些參數設定是搭配此函式使用的最有效率參數設定。 |
| 非 Null 字元 | NULL | 使用指定的預設字元，但不會設定 lpUsedDefaultChar。 |
| NULL | 非 Null 字元 | 視需要使用系統預設字元並設定 lpUsedDefaultChar 。 |
| 非 Null 字元 | 非 Null 字元 | 視需要使用指定的預設字元，並設定 lpUsedDefaultChar 。 |
從 Windows Vista 開始，此函式完全符合 UTF-8 和 UTF-16 的 Unicode 4.1 規格。 在舊版操作系統上使用的函式會編碼或譯碼 lone Surrogate halves 或不相符的 Surrogate 配對。 以舊版 Windows 撰寫的程式代碼，依賴此行為來編碼隨機非文字二進位數據可能會發生問題。 不過，使用此函式來產生有效 UTF-8 字串串的程式代碼會與舊版 Windows 操作系統的行為相同。
從 Windows 8 開始：WideCharToMultiByte 會在 Stringapiset.h 中宣告。 在 Windows 8 之前，它會在 Winnls.h 中宣告。
WC_COMPOSITECHECK和相關旗標
如同 使用 Unicode 正規化表示字串中所述，Unicode 允許多個相同字串的表示法， (以語言方式解譯) 。 例如，大寫 A (umlaut) 可以預先編譯為單一 Unicode 字碼點 “Ä” (U+00C4) 或分解為大寫 A 的組合，以及合併 dieresis 字元 (“A” + “ー”，也就是 U+0041 U+0308) 。 不過，大部分的代碼頁只提供撰寫的字元。WC_COMPOSITECHECK旗標會導致 WideCharToMultiByte 函式測試已分解的 Unicode 字元，並嘗試撰寫字元，再將它們轉換成要求的代碼頁。 此旗標僅適用於轉換成 單一位元組 (SBCS) 或 雙位元組 (DBCS ) 代碼頁 (代碼頁 < 50000，不包括代碼頁 42) 。 如果您的應用程式必須將分解的 Unicode 資料轉換成單一位元組或雙位元組代碼頁，此旗標可能很有用。 不過，並非所有字元都可以以這種方式轉換，而且儲存和儲存 Unicode 這類數據更為可靠。
當應用程式使用WC_COMPOSITECHECK時，某些字元組合可能會維持不完整，或可能會留下額外的非步調字元。 例如，A + 一個 + 一個 次合併成 Ä + 一個。 使用 WC_DISCARDNS 旗標會導致函式捨棄其他非步調字元。 使用 WC_DEFAULTCHAR 旗標會導致函式使用預設取代字元 (通常是 “？”請改為 ) 。 使用 WC_SEPCHARS 旗標會導致函式嘗試將每個額外的非步調字元轉換成目標代碼頁。 此旗標通常也會使用取代字元 (“？”) 。 不過，對於代碼頁 1258 (越南文) 和 20269，可以使用非步調字元。 這些代碼頁的轉換並不完美。 某些組合無法正確轉換成代碼頁 1258，而且WC_COMPOSITECHECK代碼頁 20269 中的數據損毀。 如先前所述，設計應用程式以儲存和儲存 Unicode 這類數據更為可靠。
範例
ISDSC_STATUS DiscpUnicodeToAnsiSize(
IN __in PWCHAR UnicodeString,
OUT ULONG *AnsiSizeInBytes
)
/*++
Routine Description:
This routine will return the length needed to represent the unicode
string as ANSI
Arguments:
UnicodeString is the unicode string whose ansi length is returned
*AnsiSizeInBytes is number of bytes needed to represent unicode
string as ANSI
Return Value:
ERROR_SUCCESS or error code
--*/
{
_try
{
*AnsiSizeInBytes = WideCharToMultiByte(CP_ACP,
0,
UnicodeString,
-1,
NULL,
0, NULL, NULL);
} _except(EXCEPTION_EXECUTE_HANDLER) {
return(ERROR_NOACCESS);
}
return((*AnsiSizeInBytes == 0) ? GetLastError() : ERROR_SUCCESS);
}
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows 2000 專業版 [傳統型應用程式 |UWP 應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [傳統型應用程式 |UWP 應用程式] |
| 目標平台 | Windows |
| 標頭 | stringapiset.h (包含 Windows.h) |
| 程式庫 | Kernel32.lib |
| DLL | Kernel32.dll |