LCMapStringA-Funktion (winnls.h)

Artikel
08/27/2023

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.

Hinweis Aus Interoperabilitätsgründen sollte die Anwendung die LCMapStringEx-FunktionlcMapString vorziehen, da Microsoft zur Verwendung von Gebietsschemanamen anstelle von Gebietsschemabezeichnern für neue Gebietsschemas migriert. Diese Empfehlung gilt insbesondere für benutzerdefinierte Gebietsschemas, einschließlich der von Microsoft erstellten Gebietsschemas. Jede Anwendung, die nur unter Windows Vista und höher ausgeführt wird, sollte LCMapStringEx verwenden.

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.

Die folgenden benutzerdefinierten Gebietsschemabezeichner werden ebenfalls unterstützt.

[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.

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 Großbuchstabenzeichenfolge eine andere Länge aufweist.

[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.

Hinweis

Der winnls.h-Header definiert LCMapString als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winnls.h (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll