MultiByteToWideChar

文字列をワイド文字列(Unicode)にマップします。この関数によってマップした文字列がマルチバイト文字セットに含まれるとは限りません。

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

パラメータ

CodePage
変換に使うコードページを指定します。システムにインストールされているコードページ、またはシステムがサポートするコードページを指定することができます。または、次のいずれかの定数を指定します。
定数意味
CP_ACPANSI コードページ
CP_MACCPMacintosh コードページ
CP_OEMCPOEM コードページ
CP_SYMBOLシンボルコードページ(42)
CP_THREAD_ACP現在のスレッドの ANSI コードページ
CP_UTF7UTF-7 を使った変換
CP_UTF8UTF-8 を使った変換

dwFlags
一連のビットフラグをセットします。構成済みワイド文字または合成ワイド文字のどちらに変換するか、制御文字の代わりにグリフ文字を使うかどうか、無効な文字をどのように処理するかを指定します。次のフラグ定数を組み合わせて指定することができます。
定数意味
MB_PRECOMPOSED常に構成済み文字(基本文字と送りなし文字の文字値が同じ文字)を使います。これが既定の変換方法です。MB_COMPOSITE は同時にセットできません。
MB_COMPOSITE常に合成文字(基本文字と送りなし文字の文字値が異なる文字)を使います。MB_PRECOMPOSED は同時にセットできません。
MB_ERR_INVALID_CHARS無効な入力文字があったときは関数が失敗し、GetLastError 関数を呼び出すと ERROR_NO_UNICODE_TRANSLATION が返ります。
MB_USEGLYPHCHARS制御文字の代わりにグリフ文字を使います。

合成文字は、それぞれが異なる文字値を持つ基本文字と送りなし文字とで構成されます。構成済み文字は、基本文字と送りなし文字の 1 つの組み合わせに 1 つの文字値が対応します。è という文字の場合、e が基本文字で綴り字記号(アクサングラーブ)が送りなし文字です。

関数の既定の動作は、構成済み形式への変換です。構成済み形式が存在しない場合は合成形式への変換を試みます。

MB_PRECOMPOSED と MB_COMPOSITE は同時にセットできません。MB_USEGLYPHCHARS と MB_ERR_INVALID_CHARS は、他のフラグの状態に関係なくセットすることができます。

lpMultiByteStr
変換する文字列へのポインタを指定します。
cchMultiByte
lpMultiByteStr が指す文字列のサイズをバイト単位で渡します。–1 を指定すると、文字列は NULL で終わっていると見なされ、長さが自動的に計算されます。
lpWideCharStr
変換後の文字列を受け取るバッファへのポインタを指定します。
cchWideChar
lpWideCharStr が指すバッファのサイズをワイド文字数の単位で指定します。0 を指定すると、必要なバッファのサイズ(ワイド文字数)が返り、lpWideCharStr が指すバッファは使われません。

戻り値

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

ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER
ERROR_NO_UNICODE_TRANSLATION

解説

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 はサポートされません。

対応情報

  Windows NT/2000:Windows NT 3.1 以降
  Windows 95/98:Windows 95 以降
  ヘッダー:winnls.h 内で宣言
  インポートライブラリ:kernel32.lib を使用

参照

WideCharToMultiByte

表示: