共用方式為

MultiByteToWideChar 函式 （stringapiset.h）

  • 發行項

將字元字串對應至UTF-16（寬字元） 字串。 字元字串不一定來自多位元組位元集。

注意 使用 MultiByteToWideChar 函式不正確，可能會危害應用程式的安全性。 呼叫此函式很容易造成緩衝區滿溢，因為 lpMultiByteStr 所指示的輸入緩衝區大小 等於字元串中的位元組數，而 lpWideCharStr 所指示的輸出緩衝區大小 等於字元數。 若要避免緩衝區滿溢，您的應用程式必須指定適合緩衝區接收之數據類型的緩衝區大小。 如需詳細資訊，請參閱 安全性考慮：國際功能。
 
附註 ANSI 代碼頁在不同的電腦上可能不同，或可以變更單一計算機，導致數據損毀。 為了最一致的結果，應用程式應該使用 Unicode，例如 UTF-8 或 UTF-16，而不是特定的代碼頁，除非舊版標準或數據格式無法使用 Unicode。 如果無法使用 Unicode，當通訊協定允許時，應用程式應該以適當的編碼名稱標記數據流。 HTML 和 XML 檔案允許標記，但文字檔則不允許。
 

語法

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 代碼頁。
注意 此值在不同的計算機上可能不同，即使是在同一個網路上也一樣。 它可以變更在同一部計算機上，導致儲存的數據變得無法復原的損毀。 此值僅供暫時使用，且永久記憶體應盡可能使用UTF-16或UTF-8。
 
注意 此值主要用於舊版程式代碼中，因此通常不需要，因為新式 Macintosh 計算機使用 Unicode 進行編碼。
 
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 必須設定為 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的 NORM_FORM 列舉，NormalizationC 會對應至 MB_PRECOMPOSED，而 NormalizationD 會對應至 MB_COMPOSITE。

如上述注意事項所述，如果未先呼叫此函式，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

另請參閱

Unicode 和字元集函式

Unicode 和字元集

WideCharToMultiByte

VBS 記憶體保護區中提供的 Vertdll API