WideCharToMultiByte

書式

int WideCharToMultiByte(
    UINT CodePage,         // コードページ
    DWORD dwFlags,         // 処理速度とマッピング方法を決定するフラグ
    LPCWSTR lpWideCharStr, // ワイド文字列のアドレス
    int cchWideChar,       // ワイド文字列の文字数
    LPSTR lpMultiByteStr,  // 新しい文字列を受け取るバッファのアドレス
    int cchMultiByte,      // 新しい文字列を受け取るバッファのサイズ
    LPCSTR lpDefaultChar,  // マップできない文字の既定値のアドレス
    LPBOOL lpUsedDefaultChar   // 既定の文字を使ったときにセットするフラグのアドレス
);

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

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

戻り値

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

引数

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

マップされない文字の処理方法を指定する一連のビットフラグをセットします。 フラグを何もセットしないと、関数の処理速度が向上します。次のフラグ定数が定義されています。

定数	意味
WC_NO_BEST_FIT_CHARS	対応するマルチバイトに直接変換されない Unicode 文字を、既定の文字に変換します（lpDefaultChar パラメータを参照）。つまり、変換した場合、Unicode 文字列に逆変換しても元の文字列と正確に一致する文字列に戻すことができない文字は、既定の文字に置き換えます。 このフラグは単独で使うことも、他の dwFlags オプションと組み合わせて使うこともできます。
WC_COMPOSITECHECK	合成文字を構成済み文字に変換します。
WC_DISCARDNS	変換時、送りなし文字を破棄します。
WC_SEPCHARS	変換時、別々の文字を生成します。これは、既定の変換動作です。
WC_DEFAULTCHAR	変換時、例外を既定の文字に置き換えます。
WC_COMPOSITECHECK	フラグをセットすると、合成文字が構成済み文字に変換されます。合成文字は、それぞれ異なる文字値を持つ基本文字と送りなし文字で構成されます。構成済み文字は、基本文字と送りなし文字の 1 つの組み合わせに 1 つの文字値が対応します。e という文字の場合、e が基本文字で綴り字記号（アクサングラーブ）が送りなし文字です。
WC_COMPOSITECHECK	フラグをセットすると、リストの最後にある 3 つのフラグ（WC_DISCARDNS、WC_SEPCHARS、WC_DEFAULTCHAR）を使って構成済み文字への変換をカスタマイズできます。これら 3 つのフラグは、ワイド文字列に含まれる基本/送りなし文字の組み合わせに対応する構成済み文字が存在しない場合の関数の動作を決定します。これら 3 つのフラグは、WC_COMPOSITECHECK フラグをセットした場合にのみ使えます。

関数の既定の動作は、対応する構成済み文字が存在しない合成文字を別々の文字に変換することです（WC_SEPCHARS）。

lpWideCharStr

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

cchWideChar

lpWideCharStr が指す文字列を構成する Unicode（16 ビット）文字の数を指定します。-1 を指定すると、文字列が NULL で終わっていると見なされ、長さが自動的に計算されます。

lpMultiByteStr

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

cchMultiByte

lpMultiByteStr が指すバッファのサイズをバイト単位で指定します。0 を指定すると、バッファに必要なバイト数が返ります（その場合、lpMultiByteStr が指すバッファは使われません）。

lpDefaultChar

指定したコードページで変換対象のワイド文字を表現できない場合に使う文字へのポインタを指定します。NULL を指定すると、システム既定値が使われます。lpDefaultChar と lpUsedDefaultChar の両方に NULL を指定すると、関数の処理速度が向上します。

lpUsedDefaultChar

既定文字が使われたかどうかを示すフラグへのポインタを指定します。指定したコードページで表現できないワイド文字が変換対象文字列に 1 つ以上含まれていた場合、TRUE に設定されます。それ以外の場合は FALSE に設定されます。このパラメータには NULL を指定できます。lpDefaultChar と lpUsedDefaultChar の両方に NULL を指定すると、関数の処理速度が向上します。

解説

lpMultiByteStr と lpWideCharStr は同じにできません。 同じにすると、関数は失敗します。 その場合、GetLastError 関数を呼び出すと ERROR_INVALID_PARAMETER が返ります。

lpDefaultChar パラメータを使って変換に使う既定文字を変更できます。

前述のように、WideCharToMultiByte 関数の処理は lpDefaultChar と lpUsedDefaultChar の両方に NULL を指定すると最も効率よくなります。 次の表に、lpDefaultChar と lpUsedDefaultChar の組み合わせによる WideCharToMultiByte の動作の違いを示します。

lpDefaultChar	LpUsedDefaultChar	結果
NULL	NULL	既定のチェックを行いません。関数の処理が最も効率よく、高速になります。
NULLでない	NULL	指定した既定文字を使いますが、lpUsedDefaultCharは設定しません。
NULL	NULLでない	システム既定文字を使い、必要に応じてlpUsedDefaultCharを設定します。
NULLでない	NULLでない	指定した既定文字を使い、必要に応じてlpUsedDefaultCharを設定します。

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

使用例

〈サンプルプログラム〉

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

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

    int ret = WideCharToMultiByte(
        CP_ACP,
        0,
        pSrc,
        -1,
        local,
        dataSize+1,
        NULL,
        NULL);

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

    return 0;
}

〈出力〉

wchar_t=WideCharToMultiByte test
char   =WideCharToMultiByte test

対応情報

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

参照

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