MultiByteToWideChar 関数 (stringapiset.h)

[アーティクル]
02/07/2024

文字列を UTF-16 (ワイド文字) 文字列にマップします。文字列は、必ずしもマルチバイト文字セットからのものではありません。

注意MultiByteToWideChar 関数を誤って使用すると、アプリケーションのセキュリティが損なわれる可能性があります。 lpMultiByteStr で示される入力バッファーのサイズが文字列内のバイト数と等しいのに対し、lpWideCharStr で示される出力バッファーのサイズが文字数と等しいため、この関数を呼び出すとバッファーオーバーランが発生する可能性があります。バッファーオーバーランを回避するには、アプリケーションでバッファーが受け取るデータ型に適したバッファーサイズを指定する必要があります。詳細については、「セキュリティに関する考慮事項: 国際機能」を参照してください。

メモ ANSI コードページは、異なるコンピューターで異なる場合があります。また、1 台のコンピューターで変更すると、データが破損する可能性があります。最も一貫性のある結果を得るには、従来の標準やデータ形式で 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	基本文字と 1 つ以上の非スペーシング文字がそれぞれ異なるコードポイント値を持つ分解文字、つまり文字を常に使用します。たとえば、Ä は A + ̈: LATIN CAPITAL LETTER A (U+0041) + COMBINING DIAERESIS (U+0308) で表されます。このフラグは、MB_PRECOMPOSEDで使用できないことに注意してください。
MB_ERR_INVALID_CHARS	無効な入力文字が見つかった場合は失敗します。 Windows Vista 以降では、アプリケーションでこのフラグが設定されていない場合、関数は無効なコードポイントを削除しません。代わりに、無効なシーケンスを U+ FFFD に置き換えます (指定したコードページに適してエンコードされます)。 Windows 2000 SP4 以降、Windows XP: このフラグが設定されていない場合、関数は不正なコードポイントを自動的に削除します。 GetLastError を呼び出すと、ERROR_NO_UNICODE_TRANSLATIONが返されます。

値

意味

MB_COMPOSITE

基本文字と 1 つ以上の非スペーシング文字がそれぞれ異なるコードポイント値を持つ分解文字、つまり文字を常に使用します。たとえば、Ä は A + ̈: LATIN CAPITAL LETTER A (U+0041) + COMBINING 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で使用しないでください。必ず、事前計算済み文字、つまり、基本文字または非スペーシング文字の組み合わせに対して 1 文字の値を持つ文字を使用します。たとえば、文字 è の場合、e は基本文字で、アクセント記号は非スペーシング文字です。 1 つの文字に対して 1 つの Unicode コードポイントが定義されている場合、アプリケーションでは、別の基本文字と非スペーシング文字の代わりに使用する必要があります。たとえば、Ä は単一の Unicode コードポイントのラテン大文字 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 をまたは 0MB_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 で示されるバッファーに必要なサイズ (文字数) です。また、無効なシーケンスが入力された場合にMB_ERR_INVALID_CHARS フラグが戻り値にどのように影響するかについては、dwFlags を参照してください。

成功しなかった場合、 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列挙体の場合、NormalizC は MB_PRECOMPOSED に対応し、NormalizD は MB_COMPOSITE に対応します。

前述のように、必要なサイズを取得するために cchWideChar を に 0 設定してこの関数を最初に呼び出さない場合は、出力バッファーを簡単にオーバーランできます。 MB_COMPOSITE フラグを使用する場合、出力は入力文字ごとに 3 文字以上の長さにできます。

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 Professional [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリ \|UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	stringapiset.h (Windows.h を含む)
Library	Kernel32.lib
[DLL]	Kernel32.dll

MultiByteToWideChar 関数 (stringapiset.h)

構文

パラメーター

戻り値

注釈

コードの例

要件

関連項目

フィードバック

フィードバック

その他のリソース