LCMapStringW 関数 (winnls.h)

[アーティクル]
08/27/2023

識別子で指定されたロケールの場合は、指定した変換を使用して 1 つの入力文字列を別の入力文字列にマップするか、入力文字列の並べ替えキーを生成します。

メモ相互運用性の理由から、Microsoft は新しいロケールのロケール識別子ではなくロケール名の使用に移行するため、アプリケーションは LCMapStringEx 関数を LCMapString よりも優先する必要があります。この推奨事項は、Microsoft によって作成されたものを含むカスタムロケールに特に適用されます。 Windows Vista 以降でのみ実行されるアプリケーションでは、 LCMapStringEx を使用する必要があります。

構文

int LCMapStringW(
  [in]            LCID    Locale,
  [in]            DWORD   dwMapFlags,
  [in]            LPCWSTR lpSrcStr,
  [in]            int     cchSrc,
  [out, optional] LPWSTR  lpDestStr,
  [in]            int     cchDest
);

パラメーター

[in] Locale

ロケールを指定するロケール識別子。 MAKELCID マクロを使用してロケール識別子を作成するか、次のいずれかの定義済み値を使用できます。

次のカスタムロケール識別子もサポートされています。

[in] dwMapFlags

文字列マッピング中に使用する変換の種類または生成する並べ替えキーの型を指定するフラグ。詳細な定義については、LCMapStringEx の dwMapFlags パラメーターを参照してください。

[in] lpSrcStr

関数によってマップされるソース文字列か、関数によって並べ替えキーの生成に使用されるソース文字列へのポインター。この文字列のサイズを 0 にすることはできません。

[in] cchSrc

lpSrcStr で示されるソース文字列のサイズ (文字単位)。ソース文字列のサイズには終端の null 文字を含めることができますが、必要はありません。終端の null 文字が含まれている場合、終了する null 文字は並べ替え不可能と見なされ、常にそれ自体にマップされるため、関数のマッピング動作は大きな影響を受けません。

アプリケーションでは、パラメーターを任意の負の値に設定して、ソース文字列が null で終わるかどうかを指定できます。この場合、 LCMapString がその文字列マッピングモードで使用されている場合、関数は文字列の長さ自体を計算し、 lpDestStr で示されるマップされた文字列を null で終了します。

アプリケーションでは、このパラメーターを 0 に設定できません。

[out, optional] lpDestStr

この関数がマップされた文字列または並べ替えキーを取得するバッファーへのポインター。

アプリケーションが関数を使用して並べ替えキーを生成する場合 (LCMAP_SORTKEY):

並べ替えキーはバッファーに格納され、バイトの不透明な配列として扱われます。格納された値には、任意の位置に埋め込まれた 0 バイトを含めることができます。
変換先の文字列には奇数バイトを含めることができます。 LCMAP_BYTEREV フラグは、偶数バイトのみを反転します。並べ替えキーの最後のバイト (奇数位置) は反転しません。

呼び出し元が文字列のサブセットを明示的に要求した場合、呼び出し元が cchDest で指定しない限り、宛先文字列に終端の null 文字は含まれません。

この関数が失敗した場合、宛先バッファーに部分的な結果が含まれているか、まったく結果が含まれない可能性があります。この場合、すべての結果が無効と見なされます。

注意

LCMAP_UPPERCASEまたはLCMAP_LOWERCASEを設定する場合、変換先の文字列はソース文字列と同じバッファーを使用できます。ただし、一部の条件により、返される大文字と小文字の文字列の長さが異なる場合があるため、これは強くお勧めしません。

[in] cchDest

lpDestStr で示される変換先文字列のサイズ (文字単位)。アプリケーションが文字列マッピングに関数を使用している場合は、このパラメーターの文字数を指定します。終了する null 文字のスペースが cchSrc に含まれている場合、 cchDest には終端の null 文字のスペースも含める必要があります。

アプリケーションが関数を使用して並べ替えキーを生成している場合は、サイズのバイト数を指定します。このバイト数には、並べ替えキー 0x00ターミネータの領域を含める必要があります。

アプリケーションは cchDest を 0 に設定できます。この場合、関数は lpDestStr パラメーターを使用せず、マップされた文字列または並べ替えキーに必要なバッファーサイズを返します。

戻り値

関数が文字列マッピングに使用されたときに成功した場合、変換された文字列の文字数が返されます (詳細については 、cchSrc と cchDest を参照してください)。

関数が文字列マッピングに使用されたときに成功すると、並べ替えキーのバイト数が返されます。

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

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

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

解説

「LCMapStringEx の備考」を参照してください。

ANSI バージョンの LCMapString は、指定されたロケールに関連付けられている既定の Windows (ANSI) コードページに基づいて、Unicode との間で文字列をマップします。この関数の ANSI バージョンが Unicode のみのロケールで使用されている場合、オペレーティングシステムがシステムの既定の Windows ANSI コードページを表すCP_ACP値を使用するため、関数は成功する可能性があります。ただし、システムコードページで未定義の文字は、文字列に疑問符 (?) として表示されます。

注意

winnls.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして LCMapString を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイルエラーまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件


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

LCMapStringW 関数 (winnls.h)

構文

パラメーター

戻り値

解説

要件

関連項目

フィードバック

フィードバック

その他のリソース