WideCharToMultiByte 関数 (stringapiset.h)

UTF-16 (ワイド文字) 文字列を新しい文字列にマップします。 新しい文字列は、必ずしもマルチバイト文字セットからのものではありません。

構文

int WideCharToMultiByte(
  [in]            UINT                               CodePage,
  [in]            DWORD                              dwFlags,
  [in]            _In_NLS_string_(cchWideChar)LPCWCH lpWideCharStr,
  [in]            int                                cchWideChar,
  [out, optional] LPSTR                              lpMultiByteStr,
  [in]            int                                cbMultiByte,
  [in, optional]  LPCCH                              lpDefaultChar,
  [out, optional] LPBOOL                             lpUsedDefaultChar
);

パラメーター

[in] CodePage

変換の実行に使用するコード ページ。 このパラメーターは、オペレーティング システムにインストールされているコード ページまたは使用可能なコード ページの値に設定できます。 コード ページの一覧については、「 コード ページ識別子」を参照してください。 アプリケーションでは、次の表に示す値のいずれかを指定することもできます。

[in] dwFlags

変換の種類を示すフラグ。 アプリケーションでは、次の値の組み合わせを指定できます。 これらのフラグが設定されていない場合、関数はより迅速に実行されます。 アプリケーションはWC_NO_BEST_FIT_CHARSを指定し、特定の値WC_DEFAULTCHARを使用してWC_COMPOSITECHECKして、考えられるすべての変換結果を取得する必要があります。 3 つの値がすべて指定されていない場合は、一部の結果が見つかりません。

以下に示すコード ページでは、 dwFlags は 0 である必要があります。 それ以外の場合、関数は ERROR_INVALID_FLAGS で失敗します。

• 50220
• 50221
• 50222
• 50225
• 50227
• 50229
• 57002 から 57011
• 65000 (UTF-7)
• 42 (シンボル)

[in] lpWideCharStr

変換する Unicode 文字列へのポインター。

[in] cchWideChar

lpWideCharStr で示される文字列のサイズ (文字単位)。 または、文字列が null で終わる場合は、このパラメーターを -1 に設定できます。 cchWideChar が 0 に設定されている場合、関数は失敗します。

このパラメーターが -1 の場合、関数は入力文字列全体 (終端の null 文字を含む) を処理します。 したがって、結果の文字列は終端の null 文字を持ち、関数によって返される長さにはこの文字が含まれます。

このパラメーターが正の整数に設定されている場合、関数は指定した文字数を正確に処理します。 指定されたサイズに終端の null 文字が含まれていない場合、結果の文字列は null で終わるのではなく、返される長さにはこの文字は含まれません。

[out, optional] lpMultiByteStr

変換された文字列を受け取るバッファーへのポインター。

[in] cbMultiByte

lpMultiByteStr で示されるバッファーのサイズ (バイト単位)。 この値が 0 の場合、関数は必要なバッファー サイズ (終端の null 文字を含むバイト単位) を返し、 lpMultiByteStr バッファーは使用しません。

[in, optional] lpDefaultChar

指定したコード ページで文字を表すことができない場合に使用する文字へのポインター。 関数がシステムの既定値を使用する場合、アプリケーションはこのパラメーターを NULL に設定します。 システムの既定の文字を取得するために、アプリケーションは GetCPInfo または GetCPInfoEx 関数 を 呼び出すことができます。

CodePage のCP_UTF7とCP_UTF8の設定では、このパラメーターを NULL に設定する必要があります。 それ以外の場合、関数は ERROR_INVALID_PARAMETER で失敗します。

[out, optional] lpUsedDefaultChar

関数が変換で既定の文字を使用したかどうかを示すフラグへのポインター。 指定したコード ページでソース文字列の 1 つ以上の文字を表すことができない場合、フラグは TRUE に設定されます。 それ以外の場合、フラグは FALSE に設定 されます。 このパラメーターは NULL に設定できます。

CodePage のCP_UTF7とCP_UTF8の設定では、このパラメーターを NULL に設定する必要があります。 それ以外の場合、関数は ERROR_INVALID_PARAMETER で失敗します。

戻り値

成功した場合は、 lpMultiByteStr が指すバッファーに書き込まれたバイト数を返します。 関数が成功し、 cbMultiByte が 0 の場合、戻り値は lpMultiByteStr で示されるバッファーに必要なサイズ (バイト単位) です。 また、無効なシーケンスが入力された場合にWC_ERR_INVALID_CHARS フラグが戻り値に与える影響については、「 dwFlags 」も参照してください。

成功しなかった場合、関数は 0 を返します。 拡張エラー情報を取得するために、アプリケーションは GetLastError を呼び出すことができます。これにより、次のいずれかのエラー コードが返されます。

• ERROR_INSUFFICIENT_BUFFER。 指定されたバッファー サイズが十分に大きくなかったか、 正しく NULL に設定されていませんでした。
• ERROR_INVALID_FLAGS。 フラグに指定された値が無効でした。
• ERROR_INVALID_PARAMETER。 パラメーター値のいずれかが無効です。
• ERROR_NO_UNICODE_TRANSLATION。 文字列に無効な Unicode が見つかりました。

注釈

lpMultiByteStr ポインターと lpWideCharStr ポインターは同じにすることはできません。 同じ場合、関数は失敗し、 GetLastError は ERROR_INVALID_PARAMETERを返します。

入力文字列の長さが null 文字を終了せずに明示的に指定されている場合、WideCharToMultiByte は出力文字列を null で終了しません。 この関数の出力文字列を null 終了するには、アプリケーションで -1 を渡すか、入力文字列の終端の null 文字を明示的にカウントする必要があります。

cbMultiByte が cchWideChar より小さい場合、この関数は cbMultiByte で指定された文字数を lpMultiByteStr で示されるバッファーに書き込みます。 ただし、 CodePage が CP_SYMBOL に設定されていて 、cbMultiByte が cchWideChar より小さい場合、この関数は lpMultiByteStr に文字を書き込まない。

WideCharToMultiByte 関数は、lpDefaultChar と lpUsedDefaultChar の両方が NULL に設定されている場合に最も効率的に動作します。 次の表は、これらのパラメーターの 4 つの可能な組み合わせに対する関数の動作を示しています。

Windows Vista 以降、この関数は UTF-8 および UTF-16 の Unicode 4.1 仕様に完全に準拠しています。 以前のオペレーティング システムで使用された関数は、単独の サロゲート の半分または不一致のサロゲート ペアをエンコードまたはデコードします。 この動作に依存してランダムな非テキスト バイナリ データをエンコードする以前のバージョンの Windows で記述されたコードは、問題が発生する可能性があります。 ただし、この関数を使用して有効な UTF-8 文字列を生成するコードは、以前の Windows オペレーティング システムと同じように動作します。

Windows 8 以降: WideCharToMultiByte は Stringapiset.h で宣言されています。 Windows 8する前は、Winnls.h で宣言されていました。

WC_COMPOSITECHECKおよび関連フラグ

WC_COMPOSITECHECK フラグを指定すると、 WideCharToMultiByte 関数は分解された Unicode 文字をテストし、要求されたコード ページに変換する前にそれらを作成しようとします。 このフラグは、 1 バイト (SBCS) または 2 バイト (DBCS) コード・ページ (コード・ページ < 50000 、コード・ページ 42 を除く) への変換にのみ使用できます。 アプリケーションで分解された Unicode データを 1 バイトまたは 2 バイトのコード ページに変換する必要がある場合は、このフラグが役立つ場合があります。 ただし、すべての文字をこのように変換できるわけではありません。Unicode などのデータを保存して格納する方が信頼性が高くなります。

アプリケーションがWC_COMPOSITECHECKを使用している場合、一部の文字の組み合わせが不完全なままになっている場合や、他の非スペーシング文字が残っている可能性があります。 たとえば、A + ̈ + ̈ は Ä + ̈ に結合されます。 WC_DISCARDNS フラグを使用すると、関数は、他の非スペーシング文字を破棄します。 WC_DEFAULTCHAR フラグを使用すると、関数は代わりに既定の置換文字 (通常は "?") を使用します。 WC_SEPCHARS フラグを使用すると、関数は、各追加の非スペーシング文字をターゲット コード ページに変換しようとします。 通常、このフラグは置換文字 ("?") を使用します。 ただし、コード ページ 1258 (ベトナム語) と 20269 では、非スペーシング文字が存在し、使用できます。 これらのコード ページの変換は完璧ではありません。 一部の組み合わせはコード ページ 1258 に正しく変換されず、WC_COMPOSITECHECKコード ページ 20269 のデータが破損します。 前述のように、Unicode などのデータを保存して格納するようにアプリケーションを設計する方が信頼性が高くなります。

例

ISDSC_STATUS DiscpUnicodeToAnsiSize(
    IN __in PWCHAR UnicodeString,
    OUT ULONG *AnsiSizeInBytes
    )
/*++
Routine Description:
    This routine will return the length needed to represent the unicode
    string as ANSI
Arguments:
    UnicodeString is the unicode string whose ansi length is returned
    *AnsiSizeInBytes is number of bytes needed to represent unicode
        string as ANSI
Return Value:
    ERROR_SUCCESS or error code
--*/
{
    _try
    {
        *AnsiSizeInBytes = WideCharToMultiByte(CP_ACP,
                                               0,
                                               UnicodeString,
                                               -1,
                                               NULL,
                                               0, NULL, NULL);
    } _except(EXCEPTION_EXECUTE_HANDLER) {
        return(ERROR_NOACCESS);
    }
    return((*AnsiSizeInBytes == 0) ? GetLastError() : ERROR_SUCCESS);
}

要件

関連項目

MultiByteToWideChar

Unicode および文字セット関数

Unicode と文字セット

VBS エンクレーブで使用できる Vertdll API