LCMapStringA-Funktion (winnls.h)

Ordnen Sie für ein durch den Bezeichner angegebenes Gebietsschema eine Eingabezeichenfolge einer anderen mithilfe einer angegebenen Transformation zu oder generiert einen Sortierschlüssel für die Eingabezeichenfolge.

Syntax

int LCMapStringA(
  [in]            LCID   Locale,
  [in]            DWORD  dwMapFlags,
  [in]            LPCSTR lpSrcStr,
  [in]            int    cchSrc,
  [out, optional] LPSTR  lpDestStr,
  [in]            int    cchDest
);

Parameter

[in] Locale

Gebietsschemabezeichner , der das Gebietsschema angibt. Sie können das MAKELCID-Makro verwenden, um einen Gebietsschemabezeichner zu erstellen oder einen der folgenden vordefinierten Werte zu verwenden.

• LOCALE_INVARIANT
• LOCALE_SYSTEM_DEFAULT
• LOCALE_USER_DEFAULT

• LOCALE_CUSTOM_DEFAULT
• LOCALE_CUSTOM_UI_DEFAULT
• LOCALE_CUSTOM_UNSPECIFIED

[in] dwMapFlags

Flags, die den Typ der Transformation angeben, die während der Zeichenfolgenzuordnung verwendet werden soll, oder den Typ des zu generierenden Sortierschlüssels. Ausführliche Definitionen finden Sie im dwMapFlags-Parameter von LCMapStringEx.

[in] lpSrcStr

Zeiger auf eine Quellzeichenfolge, die die Funktion zuordnet oder für die Sortierschlüsselgenerierung verwendet. Diese Zeichenfolge darf keine Größe von 0 aufweisen.

[in] cchSrc

Größe der quelligen Zeichenfolge, die von lpSrcStr. Die Größe der Quellzeichenfolge kann das beendende NULL-Zeichen enthalten, muss aber nicht. Wenn das beendende NULL-Zeichen enthalten ist, wird das Zuordnungsverhalten der Funktion nicht wesentlich beeinträchtigt, da das beendende NULL-Zeichen als nicht teilbar gilt und immer sich selbst zugeordnet wird.

Die Anwendung kann den Parameter auf einen beliebigen negativen Wert festlegen, um anzugeben, dass die Quellzeichenfolge NULL-beendet ist. Wenn LCMapString in diesem Fall im Zeichenfolgenzuordnungsmodus verwendet wird, berechnet die Funktion die Länge der Zeichenfolge selbst und beendet die zugeordnete Zeichenfolge, die von 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 verwendet, um einen Sortierschlüssel (LCMAP_SORTKEY) zu generieren:

• Der Sortierschlüssel wird im Puffer gespeichert und als undurchsichtiges Bytearray behandelt. Die gespeicherten Werte können eingebettete 0 Bytes an einer beliebigen Position 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 (ungerad positioniert) im Sortierschlüssel wird nicht umgekehrt.

Wenn der Aufrufer explizit eine Teilmenge der Zeichenfolge anfordert, enthält die Zielzeichenfolge kein beendendes 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 betrachtet werden.

[in] cchDest

Größe der Zielzeichenfolge, die von lpDestStr. angegeben wird, in Zeichen. Wenn die Anwendung die Funktion für die Zeichenfolgenzuordnung verwendet, stellt sie eine Zeichenanzahl für diesen Parameter bereit. Wenn leer für ein beendendes NULL-Zeichen in cchSrc enthalten ist, muss cchDest auch Leerzeichen für ein beendendes NULL-Zeichen enthalten.

Wenn die Anwendung die Funktion verwendet, um einen Sortierschlüssel zu generieren, stellt sie eine Byteanzahl für die Größe bereit. Diese Byteanzahl muss Leerzeichen für den Sortierschlüssel 0x00 Abschlusszeichen enthalten.

Die Anwendung kann cchDest auf 0 festlegen. In diesem Fall verwendet die Funktion nicht den parameter lpDestStr und gibt die erforderliche Puffergröße für die zugeordnete Zeichenfolge oder den Sortierschlüssel zurück.

Rückgabewert

Wenn die Funktion bei verwendung für die Zeichenfolgenzuordnung erfolgreich ist, gibt sie die Anzahl der Zeichen in der übersetzten Zeichenfolge zurück (weitere Details finden Sie unter cchSrc und cchDest ).

Wenn die Funktion bei verwendung für die Zeichenfolgenzuordnung erfolgreich ist, 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 abzurufen, 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.

• 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

Weitere Informationen finden Sie unter Hinweise für LCMapStringEx.

Die ANSI-Version von LCMapString ordnet Zeichenfolgen basierend auf der Windows-Standardcodepage (ANSI), die dem angegebenen Gebietsschema zugeordnet ist, zu und aus Unicode zu. Wenn die ANSI-Version dieser Funktion mit einem reinen Unicode-Gebietsschema verwendet wird, kann die Funktion erfolgreich sein, da das Betriebssystem den CP_ACP-Wert verwendet, der die Windows ANSI-Standardcodepage des Systems darstellt. Zeichen, die auf der Systemcodepage nicht definiert sind, werden jedoch in der Zeichenfolge als Fragezeichen (?) angezeigt.

Anforderungen

Siehe auch

CompareString

FindNLSString

GetNLSVersion

Behandeln der Sortierung in Ihren Anwendungen

LCMapStringEx

Unterstützung für nationale Sprachen

Nationale Sprachunterstützungsfunktionen