MultiByteToWideChar

書式

int MultiByteToWideChar(
    UINT CodePage,         // コードページ
    DWORD dwFlags,         // 文字の種類を指定するフラグ
    LPCSTR lpMultiByteStr, // マップ元文字列のアドレス
    int cchMultiByte,      // マップ元文字列のバイト数
    LPWSTR lpWideCharStr,  // マップ先ワイド文字列を入れるバッファのアドレス
    int cchWideChar        // バッファのサイズ
);

【インクルードファイル】

windows.h (winnls.h 内で宣言)

戻り値

cchWideChar に 0 以外の値を指定し、関数が成功すると、 lpWideCharStr が指すバッファに書き込まれたワイド文字の数が返ります。
cchWideChar に 0 を指定し、関数が成功すると、変換後の文字列を受け取るバッファに必要なサイズ (ワイド文字数)が返ります。
関数が失敗すると、0 が返ります。拡張エラー情報を取得するには、 GetLastError 関数を使います。GetLastError 関数は、次のいずれかのエラーコードを返します。
ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER
ERROR_NO_UNICODE_TRANSLATION

引数

CodePage

変換に使うコードページを指定します。システムにインストールされているコードページ、 またはシステムがサポートするコードページを指定することができます。 または、次のいずれかの定数を指定します。

定数	意味
CP_ACP	ANSI コードページ
CP_MACCP	Macintosh コードページ
CP_OEMCP	OEM コードページ
CP_SYMBOL	シンボルコードページ(42)
CP_THREAD_ACP	現在のスレッドの ANSI コードページ
CP_UTF7	UTF-7 を使った変換
CP_UTF8	UTF-8 を使った変換

dwFlags

一連のビットフラグをセットします。 構成済みワイド文字または合成ワイド文字のどちらに変換するか、 制御文字の代わりにグリフ文字を使うかどうか、無効な文字をどのように処理するかを指定します。 次のフラグ定数を組み合わせて指定することができます。

定数	意味
MB_PRECOMPOSED	常に構成済み文字(基本文字と送りなし文字の文字値が同じ文字)を使います。これが既定の変換方法です。MB_COMPOSITE は同時にセットできません。
MB_COMPOSITE	常に合成文字(基本文字と送りなし文字の文字値が異なる文字)を使います。MB_PRECOMPOSED は同時にセットできません。
MB_ERR_INVALID_CHARS	無効な入力文字があったときは関数が失敗し、GetLastError 関数を呼び出すと ERROR_NO_UNICODE_TRANSLATION が返ります。
MB_USEGLYPHCHARS	制御文字の代わりにグリフ文字を使います。

合成文字は、それぞれが異なる文字値を持つ基本文字と送りなし文字とで構成されます。 構成済み文字は、基本文字と送りなし文字の 1 つの組み合わせに 1 つの文字値が対応します。 e という文字の場合、e が基本文字で綴り字記号(アクサングラーブ)が送りなし文字です。
関数の既定の動作は、構成済み形式への変換です。 構成済み形式が存在しない場合は合成形式への変換を試みます。
MB_PRECOMPOSED と MB_COMPOSITE は同時にセットできません。 MB_USEGLYPHCHARS と MB_ERR_INVALID_CHARS は、他のフラグの状態に関係なくセットすることができます。

lpMultiByteStr

変換する文字列へのポインタを指定します。

cchMultiByte

lpMultiByteStr が指す文字列のサイズをバイト単位で渡します。-1 を指定すると、 文字列は NULL で終わっていると見なされ、長さが自動的に計算されます。

lpWideCharStr

変換後の文字列を受け取るバッファへのポインタを指定します。

cchWideChar

lpWideCharStr が指すバッファのサイズをワイド文字数の単位で指定します。 0 を指定すると、必要なバッファのサイズ(ワイド文字数)が返り、 lpWideCharStr が指すバッファは使われません。

解説

lpMultiByteStr と lpWideCharStr は同じにできません。同じにすると、関数が失敗します。 GetLastError 関数を呼び出すと、ERROR_INVALID_PARAMETER が返ります。
MB_ERR_INVALID_CHARS をセットした場合、変換元文字列に無効な文字があると、関数が失敗します。 無効な文字とは、MB_ERR_INVALID_CHARS をセットしなければ既定の文字に変換される文字で、 変換前は既定の文字でないものです。また、文字列の中に先行バイトがあり、 DBCS 文字列の有効な後続バイトがない場合、その先行バイトを無効な文字と見なします。 MB_ERR_INVALID_CHARS をセットした場合、無効な文字が見つかると、この関数は 0 を返し、 GetLastError 関数は ERROR_NO_UNICODE_TRANSLATION を返します。

Windows CE：CodePage パラメータで CP_UTF7 と CP_UTF8 はサポートされません。

使用例

〈サンプルプログラム〉

#include <windows.h>
#include <stdio.h>

int main()
{
    char *pSrc = "MultiByteToWideChar test";
    const unsigned int dataSize = 24;
    wchar_t wlocal[dataSize+1] = {0x00};

    int ret = MultiByteToWideChar(
        CP_ACP,
        MB_PRECOMPOSED,
        pSrc,
        dataSize,
        wlocal,
        dataSize+1);

    printf(  "char   =%s\n", pSrc);
    wprintf(L"wchar_t=%s\n", wlocal);

    return 0;
}

〈出力〉

char   =MultiByteToWideChar test
wchar_t=MultiByteToWideChar test

対応情報

  Windows NT/2000：Windows NT 3.1 以降
  Windows 95/98：Windows 95 以降

参照

  文字列をUnicode文字列に変換する (MultiByteToWideChar)