LCMapStringEx-Funktion (winnls.h)
Ordnet für ein gebietsschema, das durch den Namen angegeben ist, eine Eingabezeichenfolge einer anderen Zeichenfolge zu, indem sie eine angegebene Transformation verwendet, oder generiert einen Sortierschlüssel für die Eingabezeichenfolge.
Syntax
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
);
Parameter
[in, optional] lpLocaleName
Zeiger auf einen Gebietsschemanamen oder einen der folgenden vordefinierten Werte.
[in] dwMapFlags
Flag, das den Typ der Transformation angibt, die während der Zeichenfolgenzuordnung verwendet werden soll, oder den Typ des zu generierenden Sortierschlüssels. Dieser Parameter kann die folgenden Werte aufweisen.
| Flag | Bedeutung |
|---|---|
| LCMAP_BYTEREV | Byteumkehr verwenden. Wenn die Anwendung beispielsweise 0x3450 0x4822 übergibt, wird das Ergebnis 0x5034 0x2248. |
| LCMAP_FULLWIDTH | Verwenden Sie ggf. Unicode-Zeichen (Breitzeichen). Dieses Flag und LCMAP_HALFWIDTH schließen sich gegenseitig aus. Mit diesem Flag kann die Zuordnung die Normalisierungsform C verwenden, auch wenn ein Eingabezeichen bereits die volle Breite aufweist. Die Zeichenfolge „は“, die bereits die volle Breite aufweist, wird beispielsweise zu „ば“ normalisiert. Weitere Informationen finden Sie unter Unicode normalization forms (Unicode-Normalisierungsformen). |
| LCMAP_HALFWIDTH | Verwenden Sie ggf. schmale Zeichen. Dieses Flag und LCMAP_FULLWIDTH schließen sich gegenseitig aus. |
| LCMAP_HIRAGANA | Ordnen Sie alle Katakana-Zeichen hiragana zu. Dieses Flag und LCMAP_KATAKANA schließen sich gegenseitig aus. |
| LCMAP_KATAKANA | Ordnen Sie alle Hiragana-Zeichen katakana zu. Dieses Flag und LCMAP_HIRAGANA schließen sich gegenseitig aus. |
| LCMAP_LINGUISTIC_CASING | Verwenden Sie linguistische Regeln für die Groß- und Kleinschreibung anstelle von Dateisystemregeln (Standard). Dieses Flag ist nur mit LCMAP_LOWERCASE oder LCMAP_UPPERCASE gültig. |
| LCMAP_LOWERCASE | Ordnen Sie für Gebietsschemas und Skripts, die Groß- und Kleinbuchstaben verarbeiten können, alle Zeichen Kleinbuchstaben zu. |
| LCMAP_HASH | Gibt einen Hash der unformatierten Sortiergewichtungen einer Zeichenfolge zurück. Zeichenfolgen, die gleichwertig erscheinen, geben in der Regel denselben Hash zurück (z. B. "hello" und "HELLO" mit LCMAP_IGNORECASE). Einige komplexe Fälle, z. B. ostasiatische Sprachen, können jedoch ähnliche Zeichenfolgen mit identischer Gewichtung aufweisen, die als gleich verglichen werden, aber nicht denselben Hash zurückgeben. LCMAP_HASH erfordert, dass der Ausgabepuffer die Größe sizeof(int) aufweist. |
| LCMAP_SIMPLIFIED_CHINESE | Ordnen Sie traditionelle chinesische Zeichen zu vereinfachten chinesischen Zeichen zu. Dieses Flag und LCMAP_TRADITIONAL_CHINESE schließen sich gegenseitig aus. |
| LCMAP_SORTHANDLE Die Verwendung eines Sortierhandles führt zu minimalen Leistungsverbesserungen und wird abgeraten. |
Gibt ein Token zurück, das die aufgelösten Sortierparameter für das Gebietsschema darstellt (z. B. Gebietsschemaname), sodass zukünftige Aufrufe den Sortiernamen übergeben NULL und das zuvor abgefragte Sortierhandle als letzten Parameter (sortHandle) in nachfolgenden Aufrufen von CompareStringEx oder LCMapStringEx übergeben können.LCMAP_SORTHANDLE erfordert, dass der Ausgabepuffer die Größe sizeof(lparam) aufweist. |
| LCMAP_SORTKEY | Erstellen sie einen normalisierten Sortierschlüssel. Wenn das LCMAP_SORTKEY-Flag nicht angegeben ist, führt die Funktion eine Zeichenfolgenzuordnung durch. Ausführliche Informationen zur Sortierschlüsselgenerierung und Zeichenfolgenzuordnung finden Sie im Abschnitt Hinweise. |
| LCMAP_TITLECASE | Windows 7: Ordnen Sie alle Zeichen der Groß-/Kleinschreibung zu, in der der erste Buchstabe jedes Hauptworts groß geschrieben wird. |
| LCMAP_TRADITIONAL_CHINESE | Ordnen Sie vereinfachte chinesische Zeichen traditionellen chinesischen Zeichen zu. Dieses Flag und LCMAP_SIMPLIFIED_CHINESE schließen sich gegenseitig aus. |
| LCMAP_UPPERCASE | Ordnen Sie für Gebietsschemas und Skripts, die Groß- und Kleinbuchstaben verarbeiten können, alle Zeichen Großbuchstaben zu. |
Die folgenden Flags können allein, miteinander oder mit den LCMAP_SORTKEY- und/oder LCMAP_BYTEREV-Flags verwendet werden. Sie können jedoch nicht mit den anderen oben aufgeführten Flags kombiniert werden.
Die unten aufgeführten Flags werden nur mit dem flag LCMAP_SORTKEY verwendet.
[in] lpSrcStr
Zeiger auf eine Quellzeichenfolge, die die Funktion zuordnet oder für die Sortierschlüsselgenerierung verwendet. Diese Zeichenfolge darf nicht die Größe 0 haben.
[in] cchSrc
Größe der durch lpSrcStr. angegebenen Quellzeichenfolge in Zeichen. Die Größe der Quellzeichenfolge kann das abschließende NULL-Zeichen enthalten, muss aber nicht. Wenn das abschließende NULL-Zeichen enthalten ist, wird das Zuordnungsverhalten der Funktion nicht stark beeinflusst, da das beendende NULL-Zeichen als nicht teilbar gilt und sich immer zugeordnet wird.
Die Anwendung kann diesen Parameter auf einen beliebigen negativen Wert festlegen, um anzugeben, dass die Quellzeichenfolge NULL-beendet ist. Wenn LCMapStringEx in diesem Fall im Zeichenfolgenzuordnungsmodus verwendet wird, berechnet die Funktion die Zeichenfolgenlänge selbst und beendet die zugeordnete Zeichenfolge, die durch lpDestStr angegeben wird, null-.
Die Anwendung kann diesen Parameter nicht auf 0 festlegen.
[out, optional] lpDestStr
Zeiger auf einen Puffer, in dem diese Funktion die zugeordnete Zeichenfolge oder einen Sortierschlüssel abruft.
Wenn die Anwendung die -Funktion zum Generieren eines Sortierschlüssels (LCMAP_SORTKEY) verwendet:
- Der Sortierschlüssel wird im Puffer gespeichert und als undurchsichtiges Bytearray behandelt. Die gespeicherten Werte können an einer beliebigen Position eingebettete 0 Bytes enthalten.
- Die Zielzeichenfolge kann eine ungerade Anzahl von Bytes enthalten. Das flag LCMAP_BYTEREV kehrt nur eine gerade Anzahl von Bytes um. Das letzte Byte (ungerade Position) im Sortierschlüssel wird nicht umgekehrt.
Wenn der Aufrufer explizit eine Teilmenge der Zeichenfolge anfordert, enthält die Zielzeichenfolge kein abschließendes NULL-Zeichen, es sei denn, der Aufrufer hat es in cchDest angegeben.
Wenn diese Funktion fehlschlägt, kann der Zielpuffer entweder Teilergebnisse oder gar keine Ergebnisse enthalten. In diesem Fall sollten alle Ergebnisse als ungültig angesehen werden.
Hinweis
Beim Festlegen LCMAP_UPPERCASE oder LCMAP_LOWERCASE kann die Zielzeichenfolge denselben Puffer wie die Quellzeichenfolge verwenden. Dies wird jedoch dringend abgeraten, da einige Bedingungen dazu führen können, dass die zurückgegebene Zeichenfolge mit Groß-/Kleinschreibung eine andere Länge aufweist.
[in] cchDest
Größe der Zielzeichenfolge in Zeichen, die durch lpDestStr. angegeben wird. Wenn die Anwendung die -Funktion für die Zeichenfolgenzuordnung verwendet, stellt sie eine Zeichenanzahl für diesen Parameter bereit. Wenn das Leerzeichen für ein abschließendes NULL-Zeichen in cchSrc enthalten ist, muss cchDest auch Leerzeichen für ein abschließendes NULL-Zeichen enthalten.
Wenn die Anwendung die -Funktion verwendet, um einen Sortierschlüssel zu generieren, liefert sie eine Byteanzahl für die Größe. Diese Byteanzahl muss Platz für den Sortierschlüssel 0x00 Abschlusszeichen enthalten.
Die Anwendung kann cchDest auf 0 festlegen. In diesem Fall verwendet die Funktion nicht den lpDestStr-Parameter und gibt die erforderliche Puffergröße für die zugeordnete Zeichenfolge oder den Sortierschlüssel zurück.
[in, optional] lpVersionInformation
Zeiger auf eine NLSVERSIONINFOEX-Struktur , die die Versionsinformationen zur relevanten NLS-Funktion enthält; wird in der Regel von GetNLSVersionEx abgerufen.
Windows Vista, Windows 7: Reserviert; muss auf NULL festgelegt werden.
[in, optional] lpReserved
Reserviert; muss NULL sein.
[in, optional] sortHandle
Reserviert; muss 0 sein.
Hinweis
CompareStringEx und LCMapStringEx können ein Sortierhandle angeben (wenn der Gebietsschemaname NULL ist). Von dieser Verwendung wird für die meisten Apps abgeraten.
Rückgabewert
Wenn die Funktion erfolgreich für die Zeichenfolgenzuordnung verwendet wird, gibt sie die Anzahl der Zeichen in der übersetzten Zeichenfolge zurück (weitere Details finden Sie unter cchSrc und cchDest ).
Wenn die Funktion erfolgreich ist, wenn sie zum Generieren eines Sortierschlüssels verwendet wird, gibt sie die Anzahl der Bytes im Sortierschlüssel zurück.
Diese Funktion gibt 0 zurück, wenn sie nicht erfolgreich ist. Um erweiterte Fehlerinformationen zu erhalten, kann die Anwendung GetLastError aufrufen, wodurch einer der folgenden Fehlercodes zurückgegeben werden kann:
- ERROR_INSUFFICIENT_BUFFER. Eine angegebene Puffergröße war nicht groß genug, oder sie wurde fälschlicherweise auf NULL festgelegt.
- ERROR_INVALID_FLAGS. Die für Flags angegebenen Werte waren ungültig.
- ERROR_INVALID_PARAMETER. Jeder der Parameterwerte war ungültig.
Hinweise
Die Anwendung kann LCMapString oder LCMapStringEx verwenden, um einen Sortierschlüssel zu generieren. Dazu gibt die Anwendung LCMAP_SORTKEY für den dwMapFlags-Parameter an. Weitere Informationen finden Sie unter Behandeln der Sortierung in Ihren Anwendungen.
Hinweis
Sortierschlüssel sind undurchsichtige Bytedatenströme. Aufrufer sollten sie als Bytearray der von der API zurückgegebenen Länge behandeln und sich nicht auf eine interne Struktur verlassen, die möglicherweise vorhanden zu sein scheint. Null, ein oder mehrere Bytes im zurückgegebenen Sortierschlüssel können 0 sein. Das Fehlen oder Vorhandensein eines 0-Byte-Werts sollte nicht erwartet werden.
Eine weitere Möglichkeit für Ihre Anwendung, LCMapString oder LCMapStringEx zu verwenden, sind Zuordnungszeichenfolgen. In diesem Fall gibt die Anwendung keine LCMAP_SORTKEY für den dwMapFlags-Parameter an, sondern stellt eine andere Kombination von Flags bereit. Weitere Informationen finden Sie unter Behandeln der Sortierung in Ihren Anwendungen.
Ab Windows Vista: Diese Funktion kann Daten aus benutzerdefinierten Gebietsschemas verarbeiten. Es ist nicht garantiert, dass die Daten von Computer zu Computer oder zwischen Ausführungen einer Anwendung identisch sind. Wenn Ihre Anwendung Daten beibehalten oder übertragen muss, finden Sie weitere Informationen unter Verwenden persistenter Gebietsschemadaten.
Ab Windows 8: Wenn Ihre App Sprachtags aus dem Windows.Globalization-Namespace an diese Funktion übergibt, muss sie zuerst die Tags konvertieren, indem ResolveLocaleName aufgerufen wird.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows Vista [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winnls.h (windows.h einschließen) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |
Siehe auch
Behandeln der Sortierung in Ihren Anwendungen