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

執行轉換時要使用的代碼頁。此參數可以設定為操作系統中已安裝或可用之任何代碼頁的值。如需字碼頁的清單，請參閱字碼頁識別碼。您的應用程式也可以指定下表所示的其中一個值。

價值	意義
CP_ACP	系統預設的 Windows ANSI 代碼頁。便條：此值在不同的電腦上可能不同，甚至在同一網路上也是如此。它可以變更在同一部計算機上，導致儲存的數據變得無法復原的損毀。此值僅供暫時使用，且永久記憶體應盡可能使用UTF-16或UTF-8。
CP_MACCP	目前的系統 Macintosh 字碼頁（主要用於舊版程式碼，通常不需要，因為 Macintosh 電腦使用 Unicode 進行編碼。便條：此值在不同的電腦上可能不同，甚至在同一網路上也是如此。它可以變更在同一部計算機上，導致儲存的數據變得無法復原的損毀。此值僅供暫時使用，且永久記憶體應盡可能使用UTF-16或UTF-8。
CP_OEMCP	目前的系統 OEM 代碼頁。便條：此值在不同的電腦上可能不同，甚至在同一網路上也是如此。它可以變更在同一部計算機上，導致儲存的數據變得無法復原的損毀。此值僅供暫時使用，且永久記憶體應盡可能使用UTF-16或UTF-8。
CP_SYMBOL	符號代碼頁（42）。
CP_THREAD_ACP	目前線程的 Windows ANSI 代碼頁。便條：此值在不同的電腦上可能不同，甚至在同一網路上也是如此。它可以變更在同一部計算機上，導致儲存的數據變得無法復原的損毀。此值僅供暫時使用，且永久記憶體應盡可能使用UTF-16或UTF-8。
CP_UTF7	UTF-7。只有在由 7 位傳輸機制強制時，才使用此值。偏好使用 UTF-8。
CP_UTF8	UTF-8。

[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 會傳回 ERROR_NO_UNICODE_TRANSLATION。
MB_PRECOMPOSED	違約;請勿搭配MB_COMPOSITE使用。一律使用先行編譯字元，也就是基底或非步調字元組合具有單一字元值的字元。例如，在字元 è 中，e 是基底字元，而輔色嚴重標記是非步調字元。如果為字元定義單一 Unicode 字碼點，應用程式應該使用它，而不是個別的基底字元和非步調字元。例如，Ä 是由單一 Unicode 字碼點 LATIN 大寫字母 A WITH DIAERESIS （U+00C4）表示。
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 必須設定為或 MB_ERR_INVALID_CHARS0。否則，函式會失敗並 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。

言論

此函式的預設行為是轉譯為輸入字元字串的先行編譯形式。如果預先編譯的窗體不存在，函式會嘗試轉譯成復合表單。

警告

不正確地使用 MultiByteToWideChar 可能會危及應用程式的安全性。呼叫此函式很容易造成緩衝區滿溢，因為 lpMultiByteStr 所指出的輸入緩衝區大小等於字串中的位元組數目，而 lpWideCharStr 所指出的輸出緩衝區大小等於字元數目。若要避免緩衝區滿溢，您的應用程式必須指定適合緩衝區接收之數據類型的緩衝區大小。如需詳細資訊，請參閱安全性考量：國際功能。

ANSI 字碼頁在不同的電腦上可能不同，也可以針對單一電腦進行更改，從而導致資料損壞。為了最一致的結果，應用程式應該使用 Unicode，例如 UTF-8 或 UTF-16，而不是特定的代碼頁，除非舊版標準或數據格式無法使用 Unicode。如果無法使用 Unicode，當通訊協定允許時，應用程式應該以適當的編碼名稱標記數據流。 HTML 和 XML 檔案允許標記，但文字檔則不允許。

如果未先呼叫此函式並將 cchWideChar 設定 0 為取得所需的大小，則輸出緩衝區很容易滿溢。如果使用MB_COMPOSITE旗標，則每個輸入字元的輸出長度可以是三個或多個字元。

MB_PRECOMPOSED旗標的使用對大部分代碼頁的影響很小，因為大部分的輸入數據都已經組成。請考慮在使用 MultiByteToWideChar 進行轉換之後呼叫 NormalizeString。 NormalizeString 提供更準確、標準和一致的資料，而且速度也更快。請注意，針對傳遞至 NormalizeString 的 NORM_FORM 列舉，NormalizationC 會對應至 MB_PRECOMPOSED，而 NormalizationD 會對應至 MB_COMPOSITE。

lpMultiByteStr 和 lpWideCharStr 指標不得相同。如果它們相同，則函式會失敗，且 GetLastError 會傳回值 ERROR_INVALID_PARAMETER。

如果明確指定輸入字串長度，而沒有終止 Null 字元，則 MultiByteToWideChar 不會以 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 應用程式]
目標平臺	窗戶
Header	stringapiset.h （包括 Windows.h）
Library	Kernel32.lib
DLL檔案	Kernel32.dll