WideCharToMultiByte 関数 (stringapiset.h)

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

注意WideCharToMultiByte 関数を誤って使用すると、アプリケーションのセキュリティが損なわれる可能性があります。 この関数を呼び出すと、 lpWideCharStr で示される入力バッファーのサイズが Unicode 文字列の文字数と等しいのに対し、 lpMultiByteStr で示される出力バッファーのサイズはバイト数と等しいため、バッファー オーバーランが簡単に発生する可能性があります。 バッファー オーバーランを回避するには、アプリケーションでバッファーが受け取るデータ型に適したバッファー サイズを指定する必要があります。

UTF-16 から Unicode 以外のエンコードに変換されたデータは、コード ページが特定の Unicode データで使用されるすべての文字を表すことができるわけではないため、データ損失の可能性があります。 詳細については、「 セキュリティに関する考慮事項: 国際機能」を参照してください。

 
メモ ANSI コード ページは、異なるコンピューターで異なる場合があります。または、1 台のコンピューターに対して変更して、データが破損する可能性があります。 最も一貫性のある結果を得るには、従来の標準やデータ形式で Unicode の使用が妨げられない限り、アプリケーションでは特定のコード ページではなく、UTF-8 や UTF-16 などの Unicode を使用する必要があります。 Unicode を使用できない場合、プロトコルで許可されている場合、アプリケーションはデータ ストリームに適切なエンコード名でタグ付けする必要があります。 HTML ファイルと XML ファイルではタグ付けが可能ですが、テキスト ファイルではタグ付けできません。
 

構文

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

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

意味
CP_ACP
システムの既定の Windows ANSI コード ページ。
メモ この値は、同じネットワーク上でも、異なるコンピューターで異なる場合があります。 これは、同じコンピュータ上で変更することができ、保存されたデータが回復不能に破損する可能性があります。 この値は一時的な使用のみを目的としており、永続的なストレージでは可能な場合は UTF-16 または UTF-8 を使用する必要があります。
 
CP_MACCP
現在のシステム Macintosh コード ページ。
メモ この値は、同じネットワーク上でも、異なるコンピューターで異なる場合があります。 これは、同じコンピュータ上で変更することができ、保存されたデータが回復不能に破損する可能性があります。 この値は一時的な使用のみを目的としており、永続的なストレージでは可能な場合は UTF-16 または UTF-8 を使用する必要があります。
 
メモ この値は主にレガシ コードで使用されます。最新の Macintosh コンピューターではエンコードに Unicode が使用されるため、通常は必要ありません。
 
CP_OEMCP
現在のシステム OEM コード ページ。
メモ この値は、同じネットワーク上でも、異なるコンピューターで異なる場合があります。 これは、同じコンピュータ上で変更することができ、保存されたデータが回復不能に破損する可能性があります。 この値は一時的な使用のみを目的としており、永続的なストレージでは可能な場合は UTF-16 または UTF-8 を使用する必要があります。
 
CP_SYMBOL
Windows 2000: シンボル コード ページ (42)。
CP_THREAD_ACP
Windows 2000: 現在のスレッドの Windows ANSI コード ページ。
メモ この値は、同じネットワーク上でも、異なるコンピューターで異なる場合があります。 これは、同じコンピュータ上で変更することができ、保存されたデータが回復不能に破損する可能性があります。 この値は一時的な使用のみを目的としており、永続的なストレージでは可能な場合は UTF-16 または UTF-8 を使用する必要があります。
 
CP_UTF7
UTF-7。 この値は、7 ビットのトランスポート メカニズムによって強制される場合にのみ使用します。 UTF-8 を使用することをお勧めします。 この値を設定すると、 lpDefaultCharlpUsedDefaultChar をNULL に設定する必要があります。
CP_UTF8
UTF-8 です。 この値を設定すると、 lpDefaultCharlpUsedDefaultChar をNULL に設定する必要があります。

[in] dwFlags

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

意味
WC_COMPOSITECHECK
基本文字と非スペース文字で構成される複合文字を、それぞれ異なる文字値で変換します。 これらの文字を事前計算済み文字に変換します。この文字は、ベースと非スペースの文字の組み合わせに対して 1 つの文字値を持っています。 たとえば、文字 è では、e は基本文字で、アクセント のグレーブ マークは非スペース文字です。
メモ Windows は通常、事前に計算されたデータを含む Unicode 文字列を表しているため、WC_COMPOSITECHECK フラグを使用する必要はありません。
 

アプリケーションでは、WC_COMPOSITECHECKを次のいずれかのフラグと組み合わせて、既定値をWC_SEPCHARSできます。 これらのフラグは、Unicode 文字列内の基本の非スパシング文字の組み合わせに対して事前に計算されたマッピングがない場合に、関数の動作を決定します。 これらのフラグが指定されていない場合、関数は WC_SEPCHARS フラグが設定されているかのように動作します。 詳細については、「 解説 」セクションの「WC_COMPOSITECHECKおよび関連フラグ」を参照してください。

WC_DEFAULTCHAR 変換中に例外を既定の文字に置き換えます。
WC_DISCARDNS 変換中に非スペース文字を破棄します。
WC_SEPCHARS 既定値。 変換中に個別の文字を生成します。
 
WC_ERR_INVALID_CHARS
Windows Vista 以降: 無効な入力文字が見つかった場合、(0 を返し、最後のエラー コードをERROR_NO_UNICODE_TRANSLATIONに設定することで) 失敗します。 GetLastError の呼び出しで最後のエラー コードを取得できます。 このフラグが設定されていない場合、関数は無効なシーケンスを U+FFFD (指定されたコード ページに応じてエンコード) に置き換え、変換された文字列の長さを返すことによって成功します。 このフラグは、 CodePage が CP_UTF8 または 54936 として指定されている場合にのみ適用されることに注意してください。 他のコード ページ値では使用できません。
WC_NO_BEST_FIT_CHARS
直接変換されない Unicode 文字を 、lpDefaultChar で指定された既定の文字と同等のマルチバイトに変換します。 言い換えると、Unicode からマルチバイトに変換して Unicode に戻しても、同じ Unicode 文字が生成されない場合、関数は既定の文字を使用します。 このフラグは、単独で使用することも、他の定義されたフラグと組み合わせて使用することもできます。

ファイル名、リソース名、ユーザー名など、検証が必要な文字列の場合、アプリケーションでは常に WC_NO_BEST_FIT_CHARS フラグを使用する必要があります。 このフラグを指定すると、関数は文字を、似ているように見えるがセマンティクスが非常に異なる文字にマッピングできなくなります。 場合によっては、セマンティックの変更が極端になる場合があります。 たとえば、"∞" (無限大) のシンボルは、一部のコード ページでは 8 (8) にマップされます。

 

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

  • 50220
  • 50221
  • 50222
  • 50225
  • 50227
  • 50229
  • 57002 から 57011
  • 65000 (UTF-7)
  • 42 (記号)
メモ コード ページ 65001 (UTF-8) またはコード ページ 54936 (GB18030、Windows Vista 以降) の場合、 dwFlags は 0 またはWC_ERR_INVALID_CHARSに設定する必要があります。 それ以外の場合、関数はERROR_INVALID_FLAGSで失敗します。
 

[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 文字を明示的にカウントする必要があります。

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

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

lpDefaultChar lpUsedDefaultChar 結果
NULL NULL 既定のチェックはありません。 これらのパラメーター設定は、この関数で使用する最も効率的な設定です。
null 以外の文字 NULL 指定した既定の文字を使用しますが、 lpUsedDefaultChar は設定しません。
NULL null 以外の文字 システムの既定の文字を使用し、必要に応じて lpUsedDefaultChar を 設定します。
null 以外の文字 null 以外の文字 指定した既定の文字を使用し、必要に応じて lpUsedDefaultChar を 設定します。
 

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

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

WC_COMPOSITECHECKおよび関連するフラグ

Unicode 正規化を使用して文字列を表す」で説明したように、Unicode では、同じ文字列を複数表現できます (言語的に解釈されます)。 たとえば、1 つの Unicode コード ポイント "Ä" (U+00C4) として事前に計算するか、大文字 A と結合二次文字 ("A" + " ̈" (U+ 0041 U+0308) の組み合わせとして分解) を表すことができます。 ただし、ほとんどのコード ページでは、構成された文字のみが提供されます。

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);
}

要件

   
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリ |UWP アプリ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリ |UWP アプリ]
対象プラットフォーム Windows
ヘッダー stringapiset.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

MultiByteToWideChar

Unicode および文字セット関数

Unicode と文字セット