WideCharToMultiByte 関数 (stringapiset.h)
UTF-16 (ワイド文字) 文字列を新しい文字列にマップします。 新しい文字列は、必ずしもマルチバイト文字セットからのものではありません。
UTF-16 から Unicode 以外のエンコードに変換されたデータは、コード ページが特定の Unicode データで使用されるすべての文字を表すことができるわけではないため、データが失われる可能性があります。 詳細については、「 セキュリティに関する考慮事項: 国際機能」を参照してください。
構文
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 つの値がすべて指定されていない場合は、一部の結果が見つかりません。
| 値 | 意味 | ||||||
|---|---|---|---|---|---|---|---|
|
基本文字と非スペーシング文字で構成される複合文字を、それぞれ異なる文字値で変換します。 これらの文字を事前計算済み文字に変換します。これは、基本文字と非スペーシング文字の組み合わせに対して 1 つの文字値を持ちます。 たとえば、文字 è の場合、e は基本文字で、アクセント記号は非スペーシング文字です。 メモ Windows では通常、事前に計算されたデータを含む Unicode 文字列が表されるため、WC_COMPOSITECHECK フラグを使用する必要はありません。
アプリケーションは、WC_COMPOSITECHECKを次のいずれかのフラグと組み合わせて、既定値をWC_SEPCHARSできます。 これらのフラグは、Unicode 文字列内のベースと非スペーシング文字の組み合わせに対して事前に計算されたマッピングがない場合の関数の動作を決定します。 これらのフラグが指定されていない場合、関数は WC_SEPCHARS フラグが設定されているかのように動作します。 詳細については、「 解説 」セクションの「WC_COMPOSITECHECKおよび関連フラグ」を参照してください。
|
||||||
|
Windows Vista 以降: 無効な入力文字が見つかった場合は、失敗します (0 を返し、最後のエラー コードをERROR_NO_UNICODE_TRANSLATIONに設定します)。 GetLastError の呼び出しを使用して、最後のエラー コードを取得できます。 このフラグが設定されていない場合、関数は無効なシーケンスを U+FFFD (指定されたコード ページに応じてエンコード) に置き換え、変換された文字列の長さを返すことで成功します。 このフラグは、 CodePage が CP_UTF8 または 54936 として指定されている場合にのみ適用されることに注意してください。 他のコード ページ値と共に使用することはできません。 | ||||||
|
直接変換されない 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 (シンボル)
[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 つの可能な組み合わせに対する関数の動作を示しています。
| 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 では同じ文字列を複数表現できます (言語的に解釈されます)。 たとえば、二角かっこ付き大文字 A (umlaut) は、単一の 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 |
関連項目
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示