FindNLSStringEx-Funktion (winnls.h)

Artikel
08/27/2023

Sucht eine Unicode-Zeichenfolge (Breitzeichen) oder ihre Entsprechung in einer anderen Unicode-Zeichenfolge für ein gebietsschema, das durch den Namen angegeben wird.

Vorsicht Da Zeichenfolgen mit sehr unterschiedlichen binären Darstellungen als identisch vergleichen können, kann diese Funktion bestimmte Sicherheitsbedenken auslösen. Weitere Informationen finden Sie in der Diskussion zu Vergleichsfunktionen unter Sicherheitsüberlegungen: Internationale Features.

Syntax

int FindNLSStringEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFindNLSStringFlags,
  [in]            LPCWSTR          lpStringSource,
  [in]            int              cchSource,
  [in]            LPCWSTR          lpStringValue,
  [in]            int              cchValue,
  [out, optional] LPINT            pcchFound,
  [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] dwFindNLSStringFlags

Flags, die Details des Suchvorgangs angeben. Diese Flags schließen sich gegenseitig aus, wobei FIND_FROMSTART der Standardwert ist. Die Anwendung kann nur eines der Suchflags mit einem der Filterflags angeben, die in der nächsten Tabelle definiert sind. Wenn die Anwendung kein Flag angibt, verwendet die Funktion den Standardvergleich für das angegebene Gebietsschema. Wie unter Behandeln der Sortierung in Ihren Anwendungen erläutert, gibt es keinen binären Vergleichsmodus.

Wert	Bedeutung
FIND_FROMSTART	Durchsuchen Sie die Zeichenfolge, beginnend mit dem ersten Zeichen der Zeichenfolge.
FIND_FROMEND	Suchen Sie die Zeichenfolge in umgekehrter Richtung, beginnend mit dem letzten Zeichen der Zeichenfolge.
FIND_STARTSWITH	Testen Sie, ob der von lpStringValue angegebene Wert der erste Wert in der Quellzeichenfolge ist, die von lpStringSource angegeben wird.
FIND_ENDSWITH	Testen Sie, ob der von lpStringValue angegebene Wert der letzte Wert in der von lpStringSource angegebenen Quellzeichenfolge ist.

Die Anwendung kann die unten definierten Filterflags in Kombination mit einem Suchflag verwenden.

Wert	Bedeutung
LINGUISTIC_IGNORECASE	Ignorieren Sie die Groß- und Kleinschreibung in der Suche, sofern sie sprachlich angemessen ist. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.
LINGUISTIC_IGNOREDIACRITIC	Ignorieren Sie diakritische Elemente, sofern sie sprachlich angemessen sind. Weitere Informationen finden Sie im Abschnitt mit Hinweisen. Hinweis Dieses Flag führt nicht immer zu vorhersagbaren Ergebnissen, wenn es mit zerlegten Zeichen verwendet wird, d. h. Zeichen, in denen ein Basiszeichen und ein oder mehrere zeichenfreie Zeichen jeweils unterschiedliche Codepunktwerte aufweisen.
NORM_IGNORECASE	Ignorieren Sie die Groß- und Kleinschreibung in der Suche. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.
NORM_IGNOREKANATYPE	Unterscheiden Sie nicht zwischen Hiragana- und Katakana-Zeichen. Die entsprechenden Hiragana- und Katakana-Zeichen sind gleich.
NORM_IGNORENONSPACE	Ignorieren sie nicht überschreibende Zeichen. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.
NORM_IGNORESYMBOLS	Ignorieren Sie Symbole und Interpunktion.
NORM_IGNOREWIDTH	Ignorieren Sie den Unterschied zwischen Zeichen mit halber und voller Breite, z. B. C a t == cat. Das Formular mit voller Breite ist ein Formatierungsunterschied, der in chinesischen und japanischen Skripts verwendet wird.
NORM_LINGUISTIC_CASING	Verwenden Sie linguistische Regeln für die Groß- und Kleinschreibung anstelle von Dateisystemregeln (Standard). Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

[in] lpStringSource

Zeiger auf die Quellzeichenfolge, in der die Funktion nach der von lpStringValue angegebenen Zeichenfolge sucht.

[in] cchSource

Größe der von lpStringSource angegebenen Zeichenfolge in Zeichen mit Ausnahme des beendenden NULL-Zeichens. Die Anwendung kann für diesen Parameter keine andere negative Zahl als -1 angeben. Die Anwendung gibt -1 an, wenn die Quellzeichenfolge null-beendet ist und die Funktion die Größe automatisch berechnen soll.

[in] lpStringValue

Zeiger auf die Suchzeichenfolge, nach der die Funktion in der Quellzeichenfolge durchsucht.

[in] cchValue

Größe in Zeichen mit Ausnahme des beendenden NULL-Zeichens der durch lpStringValue angegebenen Zeichenfolge. Die Anwendung kann für diesen Parameter keine andere negative Zahl als -1 angeben. Die Anwendung gibt -1 an, wenn die Suchzeichenfolge null-beendet ist und die Funktion die Größe automatisch berechnen soll.

[out, optional] pcchFound

Zeiger auf einen Puffer, der die Länge der von der Funktion gefundenen Zeichenfolge enthält. Die Zeichenfolge kann länger oder kürzer als die Suchzeichenfolge sein. Wenn die Funktion die Suchzeichenfolge nicht findet, wird dieser Parameter nicht geändert.

Die Funktion kann NULL in diesem Parameter abrufen. In diesem Fall gibt die Funktion keinen Hinweis darauf, ob sich die Länge der gefundenen Zeichenfolge von der Länge der Quellzeichenfolge unterscheidet.

Beachten Sie, dass der Wert von pcchFound häufig mit dem in cchValue bereitgestellten Wert identisch ist, sich aber in den folgenden Fällen unterscheiden kann:

Der in cchValue angegebene Wert ist negativ.
Die Zeichenfolgen sind gleichwertig, weisen jedoch unterschiedliche Längen auf. Beispielsweise entspricht "A" plus "Ring kombinieren" (U+0041 U+030A) dem "A Ring" (U+00c5).

[in, optional] lpVersionInformation

Reserviert; muss NULL sein.

[in, optional] lpReserved

Reserviert; muss NULL sein.

[in, optional] sortHandle

Reserviert; muss 0 sein.

Rückgabewert

Gibt bei erfolgreicher Ausführung einen 0-basierten Index in die von lpStringSource angegebene Quellzeichenfolge zurück. In Kombination mit dem Wert in pcchFound stellt dieser Index die genaue Position der gesamten gefundenen Zeichenfolge in der Quellzeichenfolge bereit. Ein Rückgabewert von 0 ist ein fehlerfreier Index in die Quellzeichenfolge, und die übereinstimmende Zeichenfolge befindet sich in der Quellzeichenfolge bei Offset 0.

Die Funktion gibt -1 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_INVALID_FLAGS. Die für Flags angegebenen Werte waren ungültig.
ERROR_INVALID_PARAMETER. Jeder der Parameterwerte war ungültig.
ERROR_SUCCESS. Die Aktion wurde erfolgreich abgeschlossen, lieferte aber keine Ergebnisse.

Hinweise

Diese Funktion bietet eine Vielzahl von Suchoptionen, einschließlich Suchrichtung, Zeichenäquivalenzfilterung und gebietsschemaspezifische Filterung. Beachten Sie, dass die Äquivalenz von dem Gebietsschema und den Flags abhängt, die im Aufruf der Funktion angegeben sind. Die Filterflags können die Ergebnisse der Suche ändern. Beispielsweise erhöhen sich die potenziellen Übereinstimmungen, wenn die Funktion groß- oder diakritische Markierungen ignoriert, wenn die Suche ausgeführt wird.

Standardmäßig ordnet diese Funktion das Kleinbuchstaben "i" dem Großbuchstaben "I" zu, auch wenn der Locale-Parameter türkisch (Türkei) oder Aserbaidschanisch (Aserbaidschan) angibt. Um dieses Verhalten für Türkisch oder Aserbaidschanisch zu überschreiben, sollte die Anwendung NORM_LINGUISTIC_CASING angeben. Wenn dieses Flag für das richtige Gebietsschema angegeben wird, ist "ı" (Kleinbuchstaben punktloses I) die Kleinbuchstabenform von "I" (großgeschriebenes punktloses I) und "i" (Kleinbuchstaben gepunktetes I) ist die Kleinbuchstabenform von "ı" (Großbuchstaben gepunktetes I).

Bei vielen Skripts (insbesondere lateinischen Skripts) fällt NORM_IGNORENONSPACE mit LINGUISTIC_IGNOREDIACRITIC zusammen und NORM_IGNORECASE mit LINGUISTIC_IGNORECASE zusammen, mit folgenden Ausnahmen:

NORM_IGNORENONSPACE ignoriert jede sekundäre Unterscheidung, unabhängig davon, ob es sich um ein diakritisches oder nicht handelt. Skripts für Koreanisch, Japanisch, Chinesisch, indische Sprachen und andere verwenden diese Unterscheidung für andere Zwecke als diakritische Zwecke. LINGUISTIC_IGNOREDIACRITIC ignoriert nur die tatsächlichen Diakritischen, anstatt einfach die zweite Sortiergewichtung zu ignorieren.
NORM_IGNORECASE ignoriert jede tertiäre Unterscheidung, unabhängig davon, ob es sich tatsächlich um linguistische Fälle handelt oder nicht. In arabischen und indischen Skripts unterscheidet dieses Flag beispielsweise alternative Formen eines Zeichens. Die Unterschiede entsprechen jedoch nicht dem linguistischen Fall. LINGUISTIC_IGNORECASE ignoriert nur die tatsächliche linguistische Groß- und Kleinschreibung, anstatt die dritte Sortiergewichtung zu ignorieren.

Im Gegensatz zu anderen NLS-API-Funktionen, die bei Einem Fehler 0 zurückgeben, gibt diese Funktion -1 zurück, wenn sie fehlschlägt. Bei Erfolg wird ein 0-basierter Index zurückgegeben. Die Verwendung dieses Indexes hilft der Funktion, Off-by-One-Fehler und 1-Zeichen-Pufferüberläufe zu vermeiden.

Diese Funktion ist eine der wenigen NLS-Funktionen, die SetLastError aufruft, auch wenn sie erfolgreich ist. Dieser Aufruf wird ausgeführt, um den letzten Fehler in einem Thread zu löschen, wenn er nicht mit der Suchzeichenfolge übereinstimmt. Dadurch wird der von GetLastError zurückgegebene Wert gelöscht.

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


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