MultiByteToWideChar 函式 （stringapiset.h）
將字元字串對應至UTF-16（寬字元） 字串。 字元字串不一定來自多位元組位元集。
語法
int MultiByteToWideChar(
[in] UINT CodePage,
[in] DWORD dwFlags,
[in] _In_NLS_string_(cbMultiByte)LPCCH lpMultiByteStr,
[in] int cbMultiByte,
[out, optional] LPWSTR lpWideCharStr,
[in] int cchWideChar
);
參數
[in] CodePage
執行轉換時要使用的代碼頁。 此參數可以設定為操作系統中已安裝或可用之任何代碼頁的值。 如需代碼頁清單，請參閱 代碼頁識別碼。 您的應用程式也可以指定下表所示的其中一個值。
[in] dwFlags
指出轉換類型的旗標。 應用程式可以指定下列值的組合，MB_PRECOMPOSED為預設值。 MB_PRECOMPOSED和MB_COMPOSITE互斥。 不論其他旗標的狀態為何，都可以設定MB_USEGLYPHCHARS和MB_ERR_INVALID_CHARS。
| 價值 | 意義 |
|---|---|
| MB_COMPOSITE | 一律使用分解字元，也就是說，基底字元和一或多個非步調字元各有相異的程式代碼點值。 例如，Ä 以 A + Ü 代表：拉丁大寫字母 A （U+0041） + 結合 DIAERESIS （U+0308）。 請注意，此旗標無法與MB_PRECOMPOSED搭配使用。 |
| MB_ERR_INVALID_CHARS | 如果遇到無效的輸入字元，則失敗。 從 Windows Vista 開始，如果應用程式未設定此旗標，函式不會卸除不合法的代碼點，而是以 U+FFFD 取代不合法的序列（針對指定的代碼頁進行編碼）。 Windows 2000 SP4 和更新版本，Windows XP： 如果未設定此旗標，函式會以無訊息方式捨棄不合法的程式代碼點。 對 getLastError 呼叫 |
- MB_PRECOMPOSED
- MB_USEGLYPHCHARS
針對下列代碼頁，dwFlags 必須設定為 0。 否則，函式會失敗，並 ERROR_INVALID_FLAGS。
- 50220
- 50221
- 50222
- 50225
- 50227
- 50229
- 57002 到 57011
- 65000 （UTF-7）
- 42 （符號）
注意
針對 UTF-8 或代碼頁 54936 （GB18030，從 Windows Vista 開始），dwFlags 必須設定為 0 或 MB_ERR_INVALID_CHARS。 否則，函式會失敗，並 ERROR_INVALID_FLAGS。
[in] lpMultiByteStr
要轉換之字元字串的指標。
[in] cbMultiByte
lpMultiByteStr 參數所指示之字串的大小，以位元組為單位。 或者，如果字串以 null 終止，則可以將此參數設定為 -1。 請注意，如果 cbMultiByte 為 0，則函式會失敗。
如果此參數為 -1，函式會處理整個輸入字串，包括終止的 Null 字元。 因此，產生的 Unicode 字串具有終止的 Null 字元，而函式所傳回的長度會包含這個字元。
如果此參數設定為正整數，則函式會正好處理指定的位元元組數目。 如果提供的大小不包含終止的 Null 字元，則產生的 Unicode 字串不會以 Null 終止，而且傳回的長度不包含此字元。
[out, optional] lpWideCharStr
接收已轉換字串之緩衝區的指標。
[in] cchWideChar
大小，以字元為單位，lpWideCharStr 所指示的緩衝區，。 如果此值是 0，函式會傳回所需的緩衝區大小，以字元為單位，包括任何終止的 Null 字元，而且不會使用 lpWideCharStr 緩衝區。
傳回值
傳回寫入緩衝區的字元數，如果成功，lpWideCharStr。 如果函式成功且 cchWideChar 是 0，則傳回值是 lpWideCharStr所指示之緩衝區所需的大小。 另請參閱 dwFlags，以取得當輸入無效序列時，MB_ERR_INVALID_CHARS 旗標如何影響傳回值的資訊。
如果函式未成功，函式會傳回 0。 若要取得擴充的錯誤資訊，應用程式可以呼叫 getLastError
-
ERROR_INSUFFICIENT_BUFFER：提供的緩衝區大小不夠大，或設定為
NULL不正確。 - ERROR_INVALID_FLAGS：為旗標提供的值無效。
- ERROR_INVALID_PARAMETER：任何參數值都無效。
- ERROR_NO_UNICODE_TRANSLATION：在字串中找到無效的 Unicode。
言論
此函式的預設行為是轉譯為輸入字元字串的先行編譯形式。 如果預先編譯的窗體不存在，函式會嘗試轉譯成復合表單。
MB_PRECOMPOSED旗標的使用對大部分代碼頁的影響很小，因為大部分的輸入數據都已經組成。 請考慮使用 MultiByteToWideChar進行轉換之後呼叫 NormalizeString。
NormalizeString 提供更精確、標準和一致的數據，而且可能更快。 請注意，針對傳遞至 normalizeString
如上述注意事項所述，如果未先呼叫此函式，cchWideChar 設定為 0，即可輕鬆過度執行輸出緩衝區，以取得所需的大小。 如果使用MB_COMPOSITE旗標，則每個輸入字元的輸出長度可以是三個或多個字元。
lpMultiByteStr 和 lpWideCharStr 指標不得相同。 如果兩者相同，函式會失敗，GetLastError 會傳回值ERROR_INVALID_PARAMETER。
MultiByteToWideChar 如果未明確指定輸入字串長度，但沒有終止 Null 字元，則不會以 null 結束輸出字串。 若要以 null 終止此函式的輸出字串，應用程式應該傳入 -1，或明確計算輸入字串的終止 Null 字元。
如果已設定MB_ERR_INVALID_CHARS且來源字串中遇到無效字元，則函式會失敗。 無效的字元為下列其中一項：
- 不是來源字串中預設字元的字元，但在未設定MB_ERR_INVALID_CHARS時會轉譯為預設字元。
- 若為 DBCS 字串，則為具有前置位元組但沒有有效尾端位元組的字元。
從 Windows Vista 開始，此函式完全符合 UTF-8 和 UTF-16 的 Unicode 4.1 規格。 在舊版操作系統上使用的函式會編碼或譯碼單一 代理 半或不相符的代理字組。 以舊版 Windows 撰寫的程式代碼，依賴此行為來編碼隨機非文字二進位數據可能會發生問題。 不過，在有效 UTF-8 字串上使用此函式的程式代碼會與舊版 Windows 操作系統的行為相同。
Windows XP： 若要防止非最短格式 UTF-8 字元版本的安全性問題，MultiByteToWideChar 刪除這些字元。
從 Windows 8 開始 ：MultiByteToWideChar 會在 Stringapiset.h中宣告。 在 Windows 8 之前，它已在 Winnls.h中宣告。
程式代碼範例
catch (std::exception e)
{
// Save in-memory logging buffer to a log file on error.
::std::wstring wideWhat;
if (e.what() != nullptr)
{
int convertResult = MultiByteToWideChar(CP_UTF8, 0, e.what(), (int)strlen(e.what()), NULL, 0);
if (convertResult <= 0)
{
wideWhat = L"Exception occurred: Failure to convert its message text using MultiByteToWideChar: convertResult=";
wideWhat += convertResult.ToString()->Data();
wideWhat += L" GetLastError()=";
wideWhat += GetLastError().ToString()->Data();
}
else
{
wideWhat.resize(convertResult + 10);
convertResult = MultiByteToWideChar(CP_UTF8, 0, e.what(), (int)strlen(e.what()), &wideWhat[0], (int)wideWhat.size());
if (convertResult <= 0)
{
wideWhat = L"Exception occurred: Failure to convert its message text using MultiByteToWideChar: convertResult=";
wideWhat += convertResult.ToString()->Data();
wideWhat += L" GetLastError()=";
wideWhat += GetLastError().ToString()->Data();
}
else
{
wideWhat.insert(0, L"Exception occurred: ");
}
}
}
else
{
wideWhat = L"Exception occurred: Unknown.";
}
Platform::String^ errorMessage = ref new Platform::String(wideWhat.c_str());
// The session added the channel at level Warning. Log the message at
// level Error which is above (more critical than) Warning, which
// means it will actually get logged.
_channel->LogMessage(errorMessage, LoggingLevel::Error);
SaveLogInMemoryToFileAsync().then([=](StorageFile^ logFile) {
_logFileGeneratedCount++;
StatusChanged(this, ref new LoggingScenarioEventArgs(LoggingScenarioEventType::LogFileGenerated, logFile->Path->Data()));
}).wait();
}
GitHub 上的 Windows 通用範例 範例。
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows 2000 專業版 [傳統型應用程式 |UWP 應用程式] |
| 支援的最低伺服器 | Windows 2000 Server [傳統型應用程式 |UWP 應用程式] |
| 目標平臺 | 窗戶 |
| 標頭 | stringapiset.h （包括 Windows.h） |
| 連結庫 | Kernel32.lib |
| DLL | Kernel32.dll |