FoldStringW-Funktion (stringapiset.h)

Artikel
03/04/2024

Ordnet eine Unicode-Zeichenfolge einer anderen zu, wobei die angegebene Transformation ausgeführt wird. Eine Übersicht über die Verwendung der Zeichenfolgenfunktionen finden Sie unter Zeichenfolgen.

Vorsicht Die falsche Verwendung von FoldString kann die Sicherheit Ihrer Anwendung beeinträchtigen. Zeichenfolgen, die nicht ordnungsgemäß zugeordnet sind, können ungültige Eingaben erzeugen. Testen Sie Zeichenfolgen, um sicherzustellen, dass sie gültig sind, bevor Sie sie verwenden, und stellen Sie Fehlerhandler bereit. Weitere Informationen finden Sie unter Sicherheitsüberlegungen: Internationale Features.

Syntax

int FoldStringW(
  [in]            DWORD                         dwMapFlags,
  [in]            _In_NLS_string_(cchSrc)LPCWCH lpSrcStr,
  [in]            int                           cchSrc,
  [out, optional] LPWSTR                        lpDestStr,
  [in]            int                           cchDest
);

Parameter

[in] dwMapFlags

Flags, die den Typ der Transformation angeben, die während der Zeichenfolgenzuordnung verwendet werden soll. Für diesen Parameter ist eine Kombination der folgenden Werte gültig.

Flag	Bedeutung
MAP_COMPOSITE	Zuordnen von Zeichen mit Akzent zu zerlegten Zeichen, d. h. Zeichen, in denen ein Basiszeichen und ein oder mehrere Zeichen ohne Strich jeweils unterschiedliche Codepunktwerte aufweisen. Ä wird beispielsweise durch A + ̈: LATEINISCHER GROßBUCHSTABE A (U+0041) + KOMBINIERENDE DIAERESE (U+0308) dargestellt. Dieses Flag entspricht der Normalisierungsform D in Windows Vista. Beachten Sie, dass dieses Flag nicht mit MB_PRECOMPOSED verwendet werden kann.
MAP_EXPAND_LIGATURES	Erweitern Sie alle Ligaturzeichen, sodass sie durch ihre zweistellige Entsprechung dargestellt werden. Beispielsweise wird die Ligatur "æ" (U+00e6) auf die beiden Zeichen "a" (U+0061) + "e" (U+0065) erweitert. Dieser Wert kann nicht mit MAP_PRECOMPOSED oder MAP_COMPOSITE kombiniert werden.
MAP_FOLDCZONE	Falte Kompatibilitätszonenzeichen in Unicode-Standardäquivalente. Dieses Flag entspricht der Normalisierungsform KD in Windows Vista, wenn auch das flag MAP_COMPOSITE festgelegt ist. Wenn das zusammengesetzte Flag nicht festgelegt ist (Standard), entspricht dieses Flag der Normalisierungsform KC in Windows Vista.
MAP_FOLDDIGITS	Ordnen Sie alle Ziffern den Unicode-Zeichen 0 bis 9 zu.
MAP_PRECOMPOSED	Ordnen Sie Zeichen mit Akzenten vorkompilierten Zeichen zu, in denen der Akzent und das Basiszeichen zu einem einzelnen Zeichenwert kombiniert werden. Dieses Flag entspricht der Normalisierungsform C in Windows Vista. Dieser Wert kann nicht mit MAP_COMPOSITE kombiniert werden.

[in] lpSrcStr

Zeiger auf eine Quellzeichenfolge, die von der Funktion zugeordnet wird.

[in] cchSrc

Größe der durch lpSrcStr angegebenen Quellzeichenfolge in Zeichen, mit Ausnahme des abschließenden NULL-Zeichens. Die Anwendung kann den Parameter auf einen beliebigen negativen Wert festlegen, um anzugeben, dass die Quellzeichenfolge NULL-beendet ist. In diesem Fall berechnet die Funktion die Zeichenfolgenlänge automatisch und beendet die zugeordnete Zeichenfolge, die durch lpDestStr angegeben wird, null-.

[out, optional] lpDestStr

Zeiger auf einen Puffer, in dem diese Funktion die zugeordnete Zeichenfolge abruft.

[in] cchDest

Größe der Zielzeichenfolge in Zeichen, die durch lpDestStr. angegeben wird. 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.

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 zurück. Wenn das flag MAP_FOLDDIGITS angegeben wird, ist der Rückgabewert die maximal erforderliche Größe, auch wenn die tatsächliche Anzahl der benötigten Zeichen kleiner als die maximale Größe ist. Wenn die maximale Größe nicht übergeben wird, schlägt die Funktion mit ERROR_INSUFFICIENT_BUFFER fehl.

Rückgabewert

Gibt die Anzahl der Zeichen in der übersetzten Zeichenfolge zurück, einschließlich eines abschließenden NULL-Zeichens, wenn dies erfolgreich ist. Wenn die Funktion erfolgreich ist und der Wert von cchDest 0 ist, entspricht der Rückgabewert der Größe des Puffers, der zum Aufnehmen der übersetzten Zeichenfolge erforderlich ist, einschließlich eines abschließenden NULL-Zeichens.

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_DATA. Die Daten waren ungültig.
ERROR_INVALID_FLAGS. Die für Flags angegebenen Werte waren ungültig.
ERROR_INVALID_PARAMETER. Jeder der Parameterwerte war ungültig.
ERROR_MOD_NOT_FOUND. Das Modul wurde nicht gefunden.
ERROR_OUTOFMEMORY. Es war nicht genügend Speicher verfügbar, um diesen Vorgang abzuschließen.
ERROR_PROC_NOT_FOUND. Die erforderliche Prozedur wurde nicht gefunden.

Hinweise

Die Werte der Parameter lpSrcStr und lpDestStr dürfen nicht identisch sein. Wenn sie identisch sind, schlägt die Funktion mit ERROR_INVALID_PARAMETER fehl.

Die Kompatibilitätszone in Unicode besteht aus Zeichen im Bereich 0xF900 bis 0xFFEF, die Zeichen aus anderen Codierungsstandards für Zeichen zugewiesen sind, aber tatsächlich Varianten von Zeichen sind, die bereits in Unicode vorhanden sind. Die Kompatibilitätszone wird verwendet, um die Roundtripzuordnung zu diesen Standards zu unterstützen. Anwendungen können das flag MAP_FOLDCZONE verwenden, um die Duplizierung von Zeichen in der Kompatibilitätszone zu vermeiden.

Ab Windows Vista: Diese Funktion unterstützt die Unicode-Normalisierung. Alle Unicode-Kompatibilitätszeichen werden zugeordnet.

Ab Windows Vista: Die Transformationen, die durch die Flags MAP_FOLDCZONE, MAP_PRECOMPOSED und MAP_COMPOSITE angegeben werden, verwenden die Unicode-Normalisierungsformen KC, C und D (über die NormalizeString-Funktion ), um die Zuordnungen durchzuführen.

Ab Windows 8: Die ANSI-Version der Funktion wird in Winnls.h und die Unicode-Version in Stringapiset.h deklariert. Vor Windows 8 wurden beide Versionen in Winnls.h deklariert.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	stringapiset.h (Einschließen von Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll