LCMapStringW-Funktion (winnls.h)

Bei einem gebietsschema, das durch den Bezeichner angegeben wird, ordnet eine Eingabezeichenzeichenfolge einer anderen mithilfe einer angegebenen Transformation zu oder generiert einen Sortierschlüssel für die Eingabezeichenfolge.

Syntax

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

Parameter

[in] Locale

Gebietsschema-ID, die 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

Zeigen Sie auf eine Quellzeichenfolge, die die Funktion ordnet oder für die Sortierschlüsselgenerierung verwendet wird. Diese Zeichenfolge darf keine Größe von 0 haben.

[in] cchSrc

Größe der durch lpSrcStrangegebenen Quellzeichenfolge in Zeichen. Die Größe der Quellzeichenfolge kann das endende NULL-Zeichen enthalten, muss aber nicht. Wenn das endierende NULL-Zeichen enthalten ist, ist das Zuordnungsverhalten der Funktion nicht erheblich betroffen, da das endierende Nullzeichen als nichtortierbar betrachtet wird und sich immer selbst zugeordnet wird.

Die Anwendung kann den Parameter auf einen beliebigen negativen Wert festlegen, um anzugeben, dass die Quellzeichenfolge null-beendet ist. Wenn in diesem Fall LCMapString- im Zeichenfolgenzuordnungsmodus verwendet wird, berechnet die Funktion die Zeichenfolgenlänge selbst und beendet die zugeordnete Zeichenfolge, die durch lpDestStrangegeben wird.

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 verwendet (LCMAP_SORTKEY):

• 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 LCMAP_BYTEREV Flag 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 endendes NULL-Zeichen, es sei denn, der Aufrufer hat sie in cchDestangegeben.

Wenn diese Funktion fehlschlägt, enthält der Zielpuffer möglicherweise partielle Ergebnisse oder gar keine Ergebnisse. In diesem Fall sollten alle Ergebnisse als ungültig betrachtet werden.

[in] cchDest

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

Wenn die Anwendung die Funktion zum Generieren eines Sortierschlüssels verwendet, stellt sie eine Byteanzahl für die Größe bereit. Diese Byteanzahl muss Platz für den Sortierschlüssel 0x00 Endator 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 erfolgreich ausgeführt wird, wenn sie für die Zeichenfolgenzuordnung 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 GetLastErroraufrufen, wodurch eine 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. Ungültige Parameterwerte.

Diese Funktion gibt 0 zurück, wenn sie nicht erfolgreich ist. Um erweiterte Fehlerinformationen zu erhalten, kann die Anwendung GetLastErroraufrufen, wodurch eine 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. Ungültige Parameterwerte.

Bemerkungen

Siehe Hinweise für LCMapStringEx-.

Die ANSI-Version von LCMapString ordnet Zeichenfolgen basierend auf der dem angegebenen Gebietsschema zugeordneten Standardcodepage von Windows (ANSI) zu und von Unicode ab. Wenn die ANSI-Version dieser Funktion mit einem Nur-Unicode-Gebietsschema verwendet wird, kann die Funktion erfolgreich sein, da das Betriebssystem den CP_ACP Wert verwendet, der die standardmäßige Windows ANSI-Codeseite des Systems darstellt. Zeichen, die auf der Systemcodeseite nicht definiert sind, werden jedoch in der Zeichenfolge als Fragezeichen (?) angezeigt.

Anforderungen

Siehe auch

CompareString-

FindNLSString-

GetNLSVersion-

Behandlung der Sortierung in Ihren Anwendungen

LCMapStringEx-

Funktionen