WideCharToMultiByte

ワイド文字列(Unicode 文字列)を新しい文字列(マルチバイト文字列など)に変換します。

int WideCharToMultiByte(
    UINT   uCodePage,       // コードページ
    DWORD  dwFlags,         // フラグ
    PCWSTR pWideCharStr,    // 変換元の文字列アドレス
    int    cchWideChar,     // 文字列の長さ
    PSTR   pMultiByteStr,   // バッファアドレス
    int    cchMultiByte,    // 文字列の長さ
    PCSTR  pDefaultChar,    // デフォルトキャラクタ
    PBOOL  pUsedDefaultChar // フラグを格納するアドレス
);

KERNEL32.DLL

引数

uCodePage

変換時に使用されるコードページを指定します。このパラメータは、インストールされているかシステムで使用可能であるすべてのコードページを指定することができます。また、以下の値の1つを指定することもできます。

意味
0 (CP_ACP) ANSI コードページ
1 (CP_OEMCP) OEM コードページ
2 (CP_MACCP) Macintosh コードページ
3 (CP_THREAD_ACP) Windows 2000/XP: 呼び出しスレッドの ANSI コードページ
42 (CP_SYMBOL) Windows 2000/XP: シンボルコードページ
65000 (CP_UTF7) Windows 98/Me/NT 4.0 以降: UTF-7 を使用して変換
65001 (CP_UTF8) Windows 98/Me/NT 4.0 以降: UTF-8 を使用して変換

これを指定した場合、 dwFlags パラメータは 0 でなければなりません。

dwFlags

ビットフラグを指定します。 0 または以下の値の組み合わせを指定します。

意味
0x00000010 (WC_DISCARDNS)

変換時にノンスペーシングキャラクタを読み捨てます。

0x00000020 (WC_SEPCHARS)

変換時に separate characters に変換する。(デフォルト)

0x00000040 (WC_DEFAULTCHAR)

変換時に例外をデフォルトキャラクタに置きかえます。

0x00000200 (WC_COMPOSITECHECK)

composite キャラクタを precomposed キャラクタに変換します。

0x00000400 (WC_NO_BEST_FIT_CHARS)

Windows 2000/XP: 直接マルチバイト文字に変換できない文字をデフォルトキャラクタに置きかえます。

COMPOSITECHECK フラグが指定されると、関数は composite キャラクタを precomposed キャラクタに変換します。 composite キャラクタはベースキャラクタとノンスペーシングキャラクタから構成され、それぞれの文字が異なるキャラクタ値を持ちます。 precomposed キャラクタは、ベースキャラクタとノンスペーシングキャラクタが組み合わさった1つのキャラクタ値を持ちます。例えば、文字「 è 」では、「 e 」がベースキャラクタになり、アクセント記号「 ` 」がノンスペーシングキャラクタになります。

COMPOSITECHECK フラグを指定する時に、アプリケーションは、変換方法をカスタマイズするために WC_DISCARDNS, WC_SEPCHARS, WC_DEFAULTCHAR フラグを使用することができます。これらのフラグは、ワイド文字列中のベースキャラクタとノンスペーシングキャラクタの組み合わせに対応する precomposed マッピングが存在しない場合にどのように処理するのかを決定します。この3つのフラグは COMPOSITECHECK フラグがともに指定されている場合にのみ有効です。

pWideCharStr

変換元のワイド文字列のアドレスを指定します。

cchWideChar

pWideCharStr パラメータで表される文字列の文字数を指定します。 -1 を指定すると、ヌル終端文字までとみなされ、文字数が自動的に計算されます。

pMultiByteStr

変換された文字列を受け取るバッファのアドレスを指定します。

cchMultiByte

pMultiByteStr パラメータで指定されるバッファのサイズをバイト単位で指定します。

0 を指定すると、この関数は必要なバッファサイズを返します。

pDefaultChar

ワイド文字を指定されたコードページで表すことができなかった場合に使われるデフォルトキャラクタのアドレスを指定します。このパラメータに 0 (NULL) を指定すると、システムデフォルト値が使われます。

uCodePage パラメータに CP_UTF7 または CP_UTF8 を指定した場合は、このパラメータに 0 (NULL) を指定しなければなりません。

pUsedDefaultChar

デフォルトキャラクタが使用されたかどうかを示すフラグを格納するための変数のアドレスを指定します。変換元の文字列の1つ以上のワイド文字を指定されたコードページであらわすことができなかった場合には 1 (TRUE) が格納されます。それ以外の場合には 0 (FALSE) が格納されます。

このパラメータに 0 (NULL) を指定することもできます。

uCodePage パラメータに CP_UTF7 または CP_UTF8 を指定した場合は、このパラメータに 0 (NULL) を指定しなければなりません。

戻り値

cchMultiByte パラメータに 0 以外の値を指定して関数が成功した場合、pMultiByteStr パラメータの示すバッファにコピーされた文字列のサイズ(バイト単位)が返ります。

cchMultiByte パラメータに 0 を指定して関数が成功した場合、文字列を変換するのに必要なバッファサイズが文字数単位で返ります。

関数が失敗すると 0 が返ります。拡張エラー情報を取得するには、 GetLastError 関数を使います。 GetLastError 関数は以下の値を返します。

解説

pMultiByteStr パラメータと pWideCharStr パラメータには同じアドレスを指定してはいけません。同じアドレスを指定した場合には関数は失敗して GetLastError 関数が 87 (ERROR_INVALID_PARAMETER) を返します。

対応情報

Windows 95 以降 / Windows NT 3.1 以降