MultiByteToWideChar
文字列をワイド文字列(Unicode)にマップします。 この関数によってマップした文字列がマルチバイト文字セットに含まれるとは限りません。
書式
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)
【メモ】マルチバイト文字列からマルチバイト文字列にしたい時
例えば、入力文字列がShift_JISなのに出力はUTF-8にしたい時にはどうするか。
他のスクリプト言語(phpとか)なら一発で変換してくれますが、C言語はそうは行きません。
C言語で行う場合は、一度ワイド文字列(Unicode)にして、目的のマルチバイト文字列に変換する。
という二段階の手順を踏まなければなりません。
具体的には、入力文字列を MultiByteToWideChar() でワイド文字列(Unicode)に直し、
WideCharToMultiByte() で目的のマルチバイト文字列に変換します。