multiByteToWideChar 函式 (stringapiset.h)

發行項
08/26/2023

將字元字串對應至 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。

如果明確指定輸入字串長度而不結束 Null 字元，MultiByteToWideChar就不會以 Null 結束輸出字串。若要以 null 終止此函式的輸出字串，應用程式應該傳入 -1，或明確計算輸入字串的終止 Null 字元。

如果已設定MB_ERR_INVALID_CHARS，且來源字串中遇到無效字元，則函式會失敗。不正確字元是下列其中一項：

不是來源字串中預設字元但未設定MB_ERR_INVALID_CHARS時轉譯為預設字元的字元
若為 DBCS 字串，則為具有前置位元組但沒有有效尾端位元組的字元

從 Windows Vista 開始，此函式完全符合 UTF-8 和 UTF-16 的 Unicode 4.1 規格。在舊版作業系統上使用的函式會編碼或解碼 lone Surrogate halves 或不相符的 Surrogate 配對。以舊版 Windows 撰寫的程式碼，依賴此行為來編碼隨機非文字二進位資料可能會發生問題。不過，在有效的 UTF-8 字串上使用此函式的程式碼，其行為方式與先前的 Windows 作業系統相同。

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

另請參閱

Unicode 和字元集函式

Unicode 和字元集

WideCharToMultiByte

multiByteToWideChar 函式 (stringapiset.h)

語法

參數

傳回值

備註

程式碼範例

需求

另請參閱

意見反應

意見反應

其他資源

其他資源