LCMapStringEx 関数 (winnls.h)

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

構文

int LCMapStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwMapFlags,
  [in]            LPCWSTR          lpSrcStr,
  [in]            int              cchSrc,
  [out, optional] LPWSTR           lpDestStr,
  [in]            int              cchDest,
  [in, optional]  LPNLSVERSIONINFO lpVersionInformation,
  [in, optional]  LPVOID           lpReserved,
  [in, optional]  LPARAM           sortHandle
);

パラメーター

[in, optional] lpLocaleName

ロケール名へのポインター、または次の定義済みの値のいずれか。

• LOCALE_NAME_INVARIANT
• LOCALE_NAME_SYSTEM_DEFAULT
• LOCALE_NAME_USER_DEFAULT

[in] dwMapFlags

文字列マッピング中に使用する変換の種類または生成する並べ替えキーの型を指定するフラグ。 このパラメーターには、次の値を指定できます。

次のフラグは、単独で、互いに使用することも、LCMAP_SORTKEYフラグやLCMAP_BYTEREVフラグと共に使用することもできます。 ただし、上記の他のフラグと組み合わせることはできません。

以下に示すフラグは、LCMAP_SORTKEY フラグでのみ使用されます。

[in] lpSrcStr

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

[in] cchSrc

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

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

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

[out, optional] lpDestStr

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

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

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

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

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

[in] cchDest

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

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

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

[in, optional] lpVersionInformation

関連する NLS 機能に関するバージョン情報を含む NLSVERSIONINFOEX 構造体へのポインター。通常は GetNLSVersionEx から取得されます。

Windows Vista、Windows 7: 予約;は NULL に設定する必要があります。

[in, optional] lpReserved

予約;は NULL である必要があります。

[in, optional] sortHandle

予約;は 0 である必要があります。

戻り値

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

並べ替えキーの生成に使用されたときに関数が成功した場合は、並べ替えキーのバイト数が返されます。

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

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

注釈

アプリケーションでは、 LCMapString または LCMapStringEx を使用して並べ替えキーを生成できます。 これを行うために、アプリケーションは dwMapFlags パラメーターのLCMAP_SORTKEYを指定します。 詳細については、「 アプリケーションでの並べ替えの処理」を参照してください。

アプリケーションで LCMapString または LCMapStringEx を使用するもう 1 つの方法は、マッピング文字列です。 この場合、アプリケーションは dwMapFlags パラメーターにLCMAP_SORTKEYを指定せず、他のフラグの組み合わせを提供します。 詳細については、「 アプリケーションでの並べ替えの処理」を参照してください。

Windows Vista 以降: この関数は、 カスタム ロケールからのデータを処理できます。 データは、コンピューター間、またはアプリケーションの実行間で同じになることは保証されません。 アプリケーションでデータを永続化または送信する必要がある場合は、「 永続的なロケール データの使用」を参照してください。

Windows 8以降: アプリが Windows.Globalization 名前空間からこの関数に言語タグを渡す場合は、最初に ResolveLocaleName を呼び出してタグを変換する必要があります。

要件

関連項目

[CompareString]

FindNLSStringEx

GetNLSVersionEx

アプリケーションでの並べ替えの処理

LCMapString

各国語サポート

各国語サポート関数