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。
值 | 意義 |
---|---|
|
一律使用分解字元,也就是基底字元和一或多個非步調字元各自具有相異字碼指標值的字元。 例如,Ä 是以 A + ー:拉丁大寫字母 A (U+0041) + 結合 DIAERESIS (U+0308) 。 請注意,此旗標無法與MB_PRECOMPOSED搭配使用。 |
|
如果遇到不正確輸入字元,則失敗。
從 Windows Vista 開始,如果應用程式未設定此旗標,函式不會卸載不合法的字碼點,而是會以 U+FFFD 取代不合法的序列, (針對指定的字碼頁編碼) 。 Windows 2000 SP4 和更新版本,Windows XP: 如果未設定此旗標,函式會以無訊息方式卸載不合法的代碼點。 呼叫 GetLastError會傳回ERROR_NO_UNICODE_TRANSLATION。 |
|
預設;請勿與MB_COMPOSITE搭配使用。 一律使用先行編譯字元,也就是基底或非步調字元組合具有單一字元值的字元。 例如,在字元 è 中,e 是基底字元,而輔色符號則是非步調字元。 如果為字元定義單一 Unicode 字碼指標,則應用程式應該使用它,而不是個別的基底字元和非步調字元。 例如,Ä 是由單一 Unicode 字碼指標 LATIN 大寫字母 A WITH DIAERESIS (U+00C4) 來表示。 |
|
使用字元字元,而不是控制字元。 |
針對下列字碼頁, dwFlags 必須設定為 0。 否則,函式會因為ERROR_INVALID_FLAGS而失敗。
- 50220
- 50221
- 50222
- 50225
- 50227
- 50229
- 57002 到 57011
- 65000 (UTF-7)
- 42 (符號)
[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的NORM_FORM列舉,NormalizationC 會對應至MB_PRECOMPOSED,而 NormalizationD 會對應至MB_COMPOSITE。
如上述警告所述,如果未先使用 cchWideChar 設定為 0 呼叫此函式,即可輕鬆地過度執行輸出緩衝區,以取得所需的大小。 如果使用MB_COMPOSITE旗標,則每個輸入字元的輸出長度可以是三或多個字元。
lpMultiByteStr和lpWideCharStr指標不得相同。 如果它們相同,則函式會失敗,而 GetLastError 會傳回值ERROR_INVALID_PARAMETER。
如果明確指定輸入字串長度而不結束 Null 字元,MultiByteToWideChar就不會以 Null 結束輸出字串。 若要以 null 終止此函式的輸出字串,應用程式應該傳入 -1,或明確計算輸入字串的終止 Null 字元。
如果已設定MB_ERR_INVALID_CHARS,且來源字串中遇到無效字元,則函式會失敗。 不正確字元是下列其中一項:
- 不是來源字串中預設字元但未設定MB_ERR_INVALID_CHARS時轉譯為預設字元的字元
- 若為 DBCS 字串,則為具有前置位元組但沒有有效尾端位元組的字元
Windowsxp: 為避免非最短格式 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 應用程式] |
目標平台 | Windows |
標頭 | stringapiset.h (包含 Windows.h) |
程式庫 | Kernel32.lib |
DLL | Kernel32.dll |
另請參閱
意見反應
提交並檢視相關的意見反應