PathAllocCanonicalize-Funktion (pathcch.h)

Konvertiert eine Pfadzeichenfolge in eine kanonische Form.

Diese Funktion unterscheidet sich von PathCchCanonicalize und PathCchCanonicalizeEx dadurch, dass sie das Ergebnis auf dem Heap zurückgibt. Dies bedeutet, dass der Aufrufer die Größe der zurückgegebenen Zeichenfolge nicht deklarieren muss und die Stapelnutzung reduziert.

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

Hinweis Diese Funktion, PathCchCanonicalize oder PathCchCanonicalizeEx, sollte anstelle von PathCanonicalize verwendet werden.

Syntax

WINPATHCCHAPI HRESULT PathAllocCanonicalize(
  [in]  PCWSTR pszPathIn,
  [in]  ULONG  dwFlags,
  [out] PWSTR  *ppszPathOut
);

Parameter

[in] pszPathIn

Ein Zeiger auf einen Puffer, der die ursprüngliche Zeichenfolge enthält. Dieser Wert darf nicht NULL sein.

[in] dwFlags

Mindestens eins der folgenden Flags:

Wert	Bedeutung
PATHCCH_NONE 0x0000000	Lassen Sie die Erstellung von \\?\ Pfaden (d. h. lange Pfade) 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.
PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS 0x00000002	Erzwingt die API, den Aufrufer unabhängig vom Zustand des langen Namens des Prozesses als aktivierten langen Pfad zu behandeln. 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 die API, den Aufrufer unabhängig vom Zustand des langen Namens des Prozesses als deaktiviert zu behandeln. 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 von nachfolgenden Punkten 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 \\?\), falls nicht bereits 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 andernfalls nicht adressierbar sind. Diese Option impliziert das gleiche Verhalten wie 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.

[out] ppszPathOut

Die Adresse eines Zeigers auf einen Puffer, der bei erfolgreicher Rückgabe dieser Funktion die kanonische Pfadzeichenfolge empfängt. Es liegt in der Verantwortung des Aufrufers, diese Ressource frei zu geben, wenn sie nicht mehr benötigt wird, indem die LocalFree-Funktion aufgerufen wird. Dieser Wert darf nicht NULL sein.

Rückgabewert

Wenn diese Funktion erfolgreich ist, gibt sie S_OK zurück. Andernfalls wird ein Fehlercode HRESULT zurückgegeben.

Hinweise

Diese Funktion unterstützt die folgenden alternativen Pfadformulare:

• \\?\
• \\?\\UNC\
• \\?\Volume{guid}\

Diese Funktion konvertiert Schrägstriche (/) nicht in Schrägstriche (\). Bei nicht vertrauenswürdiger Eingabe kann diese Funktion allein nicht verwendet werden, um Pfade in eine Form zu konvertieren, die mit anderen Pfaden für Unterpfade oder Identitäten verglichen werden kann. Aufrufer, die diese Fähigkeit benötigen, sollten vor der Verwendung dieser Funktion in schräge Schrägstriche konvertieren.

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