PathCchCanonicalizeEx-Funktion (pathcch.h)

  • Artikel

Vereinfacht einen Pfad, indem Navigationselemente wie "." und ".." entfernt werden, um einen direkten, wohlgeformten Pfad zu erzeugen.

Diese Funktion unterscheidet sich von PathCchCanonicalize darin, dass ein längerer endgültiger Pfad erstellt werden kann.

Diese Funktion unterscheidet sich von PathAllocCanonicalize darin, dass der Aufrufer die Größe der zurückgegebenen Zeichenfolge deklarieren muss, die im Stapel gespeichert ist.

Diese Funktion unterscheidet sich von PathCanonicalize darin, dass Pfade mit den Präfixen "\", "\?" und "\?\UNC" akzeptiert werden.

Hinweis Diese Funktion, PathCchCanonicalize oder PathAllocCanonicalize sollte anstelle von PathCanonicalize verwendet werden, um die Möglichkeit eines Pufferüberlaufs zu verhindern.

Syntax

WINPATHCCHAPI HRESULT PathCchCanonicalizeEx(
  [out] PWSTR  pszPathOut,
  [in]  size_t cchPathOut,
  [in]  PCWSTR pszPathIn,
  [in]  ULONG  dwFlags
);

Parameter

[out] pszPathOut

Ein Zeiger auf einen Puffer, der die bearbeitete Pfadzeichenfolge empfängt, wenn diese Funktion erfolgreich zurückgibt.

[in] cchPathOut

Die Größe des Puffers, auf den pszPathOut in Zeichen verweist.

[in] pszPathIn

Ein Zeiger auf die ursprüngliche Pfadzeichenfolge. Wenn dieser Wert NULL ist, auf eine leere Zeichenfolge verweist oder zu einer leeren Zeichenfolge führt, sobald die Elemente "." und ".." entfernt werden, wird ein einzelner umgekehrter Schrägstrich in den Puffer kopiert, auf den pszPathOut verweist.

[in] dwFlags

Mindestens eins der folgenden Flags:

Wert Bedeutung
PATHCCH_NONE
0x0000000
 Lassen Sie die Erstellung von \\?\?\-Pfaden (d. h. langen Pfaden) nicht zu, die länger als MAX_PATH sind.
PATHCCH_ALLOW_LONG_PATHS
0x00000001
 Lassen Sie die Erstellung von \\?\-Pfaden zu, die länger als MAX_PATH sind. Beachten Sie, dass cchPathOut größer als MAX_PATH sein muss. Wenn dies nicht der Fall ist, wird dieses Flag ignoriert.
PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS
0x00000002
 Erzwingt, dass die API den Aufrufer unabhängig vom Status long name enabled des Prozesses als long path enabled (langer Pfad aktiviert) behandelt. Diese Option kann nur verwendet werden, wenn PATHCCH_ALLOW_LONG_PATHS angegeben ist, und kann nicht mit PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS verwendet werden.

Hinweis Dieser Wert ist ab Windows 10 Version 1703 verfügbar.
PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS
0x00000004
 Erzwingt, dass die API den Aufrufer unabhängig vom status long name enabled des Prozesses als langer Pfad deaktiviert behandelt. Diese Option kann nur verwendet werden, wenn PATHCCH_ALLOW_LONG_PATHS angegeben ist, und kann nicht mit PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS verwendet werden.

Hinweis Dieser Wert ist ab Windows 10 Version 1703 verfügbar.
PATHCCH_DO_NOT_NORMALIZE_SEGMENTS
0x00000008
 Deaktiviert die Normalisierung von Pfadsegmenten, die das Entfernen nachgestellter Punkte und Leerzeichen umfasst. Dadurch wird der Zugriff auf Pfade ermöglicht, die durch die Win32-Pfadnormalisierung blockiert werden.

Hinweis Dieser Wert ist ab Windows 10 Version 1703 verfügbar.
PATHCCH_ENSURE_IS_EXTENDED_LENGTH_PATH
0x00000010
 Konvertiert den Eingabepfad in das DOS-Gerätepfadformular mit erweiterter Länge (mit dem Präfix \\?\), sofern noch nicht in diesem Formular vorhanden. Dies ermöglicht den Zugriff auf Pfade, die aufgrund von Win32-Normalisierungsregeln (die nachfolgende Punkte und Leerzeichen entfernen können) und Pfadlängenbeschränkungen nicht adressierbar sind. Diese Option impliziert das gleiche Verhalten von PATHCCH_DO_NOT_NORMALIZE_SEGMENTS.

Hinweis Dieser Wert ist ab Windows 10 Version 1703 verfügbar.
PATHCCH_ENSURE_TRAILING_SLASH
0x00000020
 Stellen Sie beim Kombinieren oder Normalisieren eines Pfads sicher, dass ein nachgestellter umgekehrter Schrägstrich vorliegt.

Hinweis Dieser Wert ist ab Windows 10 Version 1703 verfügbar.

Rückgabewert

Wenn diese Funktion erfolgreich ist, wird S_OK zurückgegeben. Andernfalls wird ein HRESULT-Code zurückgegeben, einschließlich, aber nicht beschränkt auf Folgendes.

Rückgabecode Beschreibung
E_INVALIDARG
 Der cchPathOut-Wert ist größer als PATHCCH_MAX_CCH.
PATHCCH_E_FILENAME_TOO_LONG
 Ein Pfadsegment enthält mehr als PATHCCH_MAX_CCH Zeichen oder überschreitet, wenn das PATHCCH_ALLOW_LONG_PATHS-Flag nicht festgelegt ist, die Standardlänge des Pfadsegments von 256 Zeichen.
E_OUTOFMEMORY
 Die Funktion konnte keinen Puffer der erforderlichen Größe zuordnen.

Hinweise

Diese Funktion antwortet auf die in einen Pfad eingebetteten Zeichenfolgen "." und "..". Die Zeichenfolge ".." gibt an, dass das unmittelbar vorangehende Pfadsegment entfernt werden soll. Die Zeichenfolge "." gibt an, dass das nächste Pfadsegment übersprungen werden soll. Beachten Sie, dass das Stammsegment des Pfads nicht entfernt werden kann. Wenn mehr ".."-Zeichenfolgen vorhanden sind, als Pfadsegmente vorhanden sind, gibt die Funktion S_OK zurück, und der Puffer, auf den pszPathOut verweist, enthält einen einzelnen umgekehrten Schrägstrich , "\".

Alle nachfolgenden Zeiträume werden aus dem Pfad entfernt, es sei denn, sie werden mit dem wilden Karte Zeichen "" vorangestellt. In diesem Fall wird ein einzelner Punkt nach dem Zeichen "" beibehalten, aber alle anderen nachfolgenden Zeiträume werden entfernt.

Wenn der resultierende Pfad ein Stammlaufwerk ("x:") ist, wird ein umgekehrter Schrägstrich ("x:\") angefügt.

Diese Funktion konvertiert schräge Schrägstriche (/) nicht in Schrägstriche (\). Bei nicht vertrauenswürdiger Eingabe kann diese Funktion selbst nicht verwendet werden, um Pfade in ein Formular zu konvertieren, das mit anderen Pfaden für Unterpfad oder Identität verglichen werden kann. Aufrufer, die diese Fähigkeit benötigen, sollten schräge Schrägstriche konvertieren, bevor sie diese Funktion verwenden.

Die folgenden Beispiele zeigen die Auswirkungen dieser Zeichenfolgen.

Ursprüngliche Zeichenfolge Kanonisierte Zeichenfolge
C:\name_1\.\name_2\.. \name_3 C:\name_1\name_3
C:\name_1\.. \name_2\.\name_3 C:\name_2\name_3
C:\name_1\name_2\.\name_3\.. \name_4 C:\name_1\name_2\name_4
C:\name_1\.\name_2\.\name_3\.. \name_4\.. C:\name_1\name_2
C:\name_1\*... C:\name_1\*.
C:\.. C:\

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 8 [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2012 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile pathcch.h
Bibliothek Pathcch.lib

Weitere Informationen

PathCchCanonicalize