LCMapStringEx

名前で指定されたロケールに対し、入力文字列を指定した変換で別の文字列へマップするか、入力文字列のソート キーを生成する。注: Windows Vista 以降のみで動作するよう設計されているアプリケーションは、LCMapString よりこの関数を優先して呼ぶべきである。

LCMapStringEx lpLocaleName, dwMapFlags, lpSrcStr, cchSrc, lpDestStr, cchDest, lpVersionInformation, lpReserved, sortHandle

lpLocaleName : [wstr] ロケール名、または次の定義済み値のいずれかへのポインタ。
dwMapFlags : [int] 文字列マッピングで使う変換の種類、または生成するソート キーの種類を指定するフラグ。このパラメータには次の値を指定できる。| フラグ | 意味 | | --- | --- | | **LCMAP_BYTEREV**| バイト反転を使う。例えば、アプリケーションが 0x3450 0x4822 を渡すと結果は 0x5034 0x2248 となる。 | | **LCMAP_FULLWIDTH** | 該当する場合に Unicode（全角）文字を使う。このフラグと LCMAP_HALFWIDTH は相互排他である。このフラグを指定すると、入力文字が既に全角であっても Normalization Form C が使われる場合がある。例えば、（既に全角の）"は゛" は "ば" に正規化される。[Unicode 正規化形式](http://www.unicode.org/reports/tr15/) を参照のこと。| |**LCMAP_HALFWIDTH** | 該当する場合に半角文字を使う。このフラグと LCMAP_FULLWIDTH は相互排他である。 | | **LCMAP_HIRAGANA** | すべてのカタカナ文字をひらがなにマップする。このフラグと LCMAP_KATAKANA は相互排他である。| | **LCMAP_KATAKANA** | すべてのひらがな文字をカタカナにマップする。このフラグと LCMAP_HIRAGANA は相互排他である。 | | **LCMAP_LINGUISTIC_CASING** | ケース処理にファイル システム ルール（既定）ではなく言語的ルールを使う。LCMAP_LOWERCASE または LCMAP_UPPERCASE とのみ組み合わせて有効である。| | **LCMAP_LOWERCASE** | 大文字・小文字を扱えるロケールやスクリプトの場合、すべての文字を小文字にマップする。| **LCMAP_HASH** | 文字列の生ソート重みのハッシュを返す。同等に見える文字列は通常同じハッシュを返す（例: LCMAP_IGNORECASE 付きでの "hello" と "HELLO"）。ただし東アジア言語などの複雑なケースでは、等しいと比較される同じ重みの類似文字列でも同じハッシュを返さないことがある。LCMAP_HASH は出力バッファのサイズが sizeof(int) であることを要求する。 | | **LCMAP_SIMPLIFIED_CHINESE** | 繁体字中国語を簡体字中国語にマップする。このフラグと LCMAP_TRADITIONAL_CHINESE は相互排他である。| | **LCMAP_SORTHANDLE**  **ソート ハンドルの使用はパフォーマンス向上がごくわずかであり推奨されない。** | ロケールに対して解決されたソート パラメータ（ロケール名のようなもの）を表すトークンを返し、以後の [CompareStringEx](../stringapiset/nf-stringapiset-comparestringex.md) や [LCMapStringEx](nf-winnls-lcmapstringex.md) 呼び出しで、ソート名に NULL を渡し、最後のパラメータ (sortHandle) として以前取得したソート ハンドルを渡せるようにする。LCMAP_SORTHANDLE は出力バッファのサイズが sizeof(lparam) であることを要求する。| | **LCMAP_SORTKEY** | 正規化済みソート キーを生成する。LCMAP_SORTKEY フラグを指定しない場合、関数は文字列マッピングを行う。ソート キー生成と文字列マッピングの詳細は Remarks を参照のこと。| | **LCMAP_TITLECASE** | Windows 7: すべての文字をタイトル ケース（各主要語の最初の文字を大文字）にマップする。 | | **LCMAP_TRADITIONAL_CHINESE** | 簡体字中国語を繁体字中国語にマップする。このフラグと LCMAP_SIMPLIFIED_CHINESE は相互排他である。| | **LCMAP_UPPERCASE** | 大文字・小文字を扱えるロケールやスクリプトの場合、すべての文字を大文字にマップする。| 次のフラグは単独、相互間、もしくは LCMAP_SORTKEY や LCMAP_BYTEREV フラグと組み合わせて使用できる。ただし、上記の他のフラグとは組み合わせできない。
lpSrcStr : [wstr] 関数がマップまたはソート キー生成に使う変換元文字列へのポインタ。この文字列のサイズは 0 にできない。
cchSrc : [int] lpSrcStr が示す変換元文字列のサイズ（文字数単位）。変換元文字列のサイズには終端 null 文字を含めてもよいが、含めなくてもよい。終端 null 文字はソート不可能な文字として扱われ常に自分自身にマップされるため、含めても関数のマッピング動作に大きな影響はない。アプリケーションはこのパラメータに任意の負の値を指定して、変換元文字列が null 終端であることを示せる。この場合、LCMapStringEx が文字列マッピング モードで使われているなら、関数は文字列長を自身で計算し、lpDestStr が示す変換後文字列を null 終端する。このパラメータを 0 にはできない。
lpDestStr : [wstr] この関数が変換後文字列またはソート キーを取得するバッファへのポインタ。アプリケーションがソート キー生成 (LCMAP_SORTKEY) に使う場合: - ソート キーはバッファに格納され、不透明なバイト配列として扱われる。格納値には任意の位置に 0 バイトが埋め込まれることがある。- 変換先文字列には奇数バイトが含まれることがある。LCMAP_BYTEREV フラグは偶数バイトのみを反転し、ソート キーの最後のバイト（奇数位置）は反転されない。呼び出し側が文字列の一部を明示的に要求した場合、cchDest で指定しない限り変換先文字列には終端 null 文字が含まれない。関数が失敗すると、変換先バッファには部分結果または何の結果も含まれないことがある。この場合、すべての結果を無効と見なすべきである。> [!NOTE] > LCMAP_UPPERCASE や LCMAP_LOWERCASE を設定するとき、変換先文字列は変換元文字列と同じバッファを使える。しかし、状況によってケース変換後の文字列の長さが変わる可能性があるため、これは強く非推奨である。
cchDest : [int] lpDestStr が示す変換先文字列のサイズ（文字数単位）。文字列マッピングに使う場合、このパラメータには文字数を指定する。cchSrc に終端 null 文字のための領域を含める場合、cchDest にも終端 null 文字のための領域を含めなければならない。ソート キー生成に使う場合はバイト数を指定する。このバイト数にはソート キーの 0x00 終端の領域を含めなければならない。cchDest を 0 にできる。この場合、関数は lpDestStr パラメータを使わず、変換後文字列またはソート キーに必要なバッファサイズを返す。
lpVersionInformation : [var] 関連する NLS 機能のバージョン情報を含む NLSVERSIONINFOEX 構造体へのポインタ。通常は GetNLSVersionEx から取得する。**Windows Vista、Windows 7:** 予約。NULL に設定しなければならない。
lpReserved : [intptr] 予約。NULL でなければならない。
sortHandle : [intptr] 予約。0 でなければならない。> [!NOTE] > [CompareStringEx](../stringapiset/nf-stringapiset-comparestringex.md) と [LCMapStringEx](nf-winnls-lcmapstringex.md) は（ロケール名が null の場合に）ソート ハンドルを指定できるが、多くのアプリケーションにとってこの使用は推奨されない。

(プラグイン / モジュール : kernel32.dll)

解説

名前で指定されたロケールに対し、入力文字列を指定した変換で別の文字列へマップするか、入力文字列のソート キーを生成する。注:
Windows Vista 以降のみで動作するよう設計されているアプリケーションは、LCMapString
よりこの関数を優先して呼ぶべきである。

[戻り値]
文字列マッピング用途で成功した場合、変換後文字列の文字数を返す（詳細は *cchSrc* および *cchDest*
を参照のこと）。ソート キー生成用途で成功した場合、ソート キーのバイト数を返す。成功しなかった場合は 0
を返す。拡張エラー情報を取得するには、アプリケーションから GetLastError を呼ぶ。次のいずれかのエラーコードが返ることがある:
（以下省略）

[備考]
アプリケーションは LCMapString または LCMapStringEx でソート キーを生成できる。そのためには
dwMapFlags パラメータに LCMAP_SORTKEY を指定する。詳細は Handling Sorting in Your
Applications を参照のこと。> [!NOTE] > ソート キーは不透明なバイト列である。呼び出し側は API
が返す長さのバイト配列として扱い、見かけ上存在しそうな内部構造に頼ってはならない。返されたソート キーのバイトには 0 が 0 個、1
個、または複数個含まれることがある。0
バイトが無いこと、あること、いずれも期待してはならない。もう一つの用途は文字列マッピングである。この場合、アプリケーションは
dwMapFlags パラメータに LCMAP_SORTKEY を指定せず、他のフラグの組み合わせを指定する。詳細は Handling
Sorting in Your Applications を参照のこと。Windows Vista 以降: この関数はカスタム
ロケールのデータを扱える。データがコンピュータ間やアプリケーションの実行間で同じである保証はない。アプリケーションがデータを永続化または送信する必要がある場合は
Using Persistent Locale Data を参照のこと。Windows 8 以降: アプリケーションが
Windows.Globalization 名前空間から言語タグをこの関数に渡す場合、まず ResolveLocaleName
を呼んでタグを変換しなければならない。

情報