PathAllocCanonicalize-Funktion (pathcch.h)

Artikel
02/23/2025

Konvertiert eine Pfadzeichenfolge in eine kanonische Form.

Diese Funktion unterscheidet sich von PathCchCanonicalize und PathCchCanonicalizeEx darin, dass das Ergebnis für den Heap zurückgegeben wird. Dies bedeutet, dass der Aufrufer die Größe der zurückgegebenen Zeichenfolge nicht deklarieren muss und die Stapelverwendung reduziert.

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

Note This function, PathCchCanonicalize, or PathCchCanonicalizeEx, should be used in place of PathCanonicalize.

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 kann nicht NULL-werden.

[in] dwFlags

Mindestens eine der folgenden Flags:

Wert	Bedeutung
PATHCCH_NONE 0x0000000	Die Erstellung von \\?\-Pfaden (dh langen Pfaden) darf nicht länger als MAX_PATH zulässig sein.
PATHCCH_ALLOW_LONG_PATHS 0x00000001	Das Erstellen von \\?\-Pfaden zulassen, die länger als MAX_PATH sind.
PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS 0x00000002	Erzwingt die API, den Aufrufer so zu behandeln, dass der lange Pfad aktiviert ist, unabhängig vom Status des langen Namens des Prozesses. Diese Option kann nur verwendet werden, wenn PATHCCH_ALLOW_LONG_PATHS angegeben wird und nicht mit PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESSverwendet werden kann. Hinweis Dieser Wert ist ab Windows 10, Version 1703, verfügbar.
PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS 0x00000004	Erzwingt die API, den Aufrufer so zu behandeln, dass der lange Pfad deaktiviert ist, unabhängig vom Status des langen Namens des Prozesses. Diese Option kann nur verwendet werden, wenn PATHCCH_ALLOW_LONG_PATHS angegeben wird und nicht mit PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESSverwendet werden kann. Hinweis Dieser Wert ist ab Windows 10, Version 1703, verfügbar.
PATHCCH_DO_NOT_NORMALIZE_SEGMENTS 0x00000008	Deaktiviert die Normalisierung von Pfadsegmenten, die nachfolgende Punkte und Leerzeichen entfernen. Dadurch wird der Zugriff auf Pfade ermöglicht, die die Win32-Pfadnormalisierung blockieren. Hinweis Dieser Wert ist ab Windows 10, Version 1703, verfügbar.
PATHCCH_ENSURE_IS_EXTENDED_LENGTH_PATH 0x00000010	Wandelt den Eingabepfad in das Formular für den erweiterten DOS-Gerätepfad (mit dem Präfix \\?\) um, wenn er noch nicht in diesem Formular vorhanden ist. Dies ermöglicht den Zugriff auf Pfade, die andernfalls 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 vorhanden ist. Hinweis Dieser Wert ist ab Windows 10, Version 1703, verfügbar.
PATHCCH_CANONICALIZE_SLASHES 0x00000040	Konvertieren Sie Schrägstriche in Schrägstriche, und reduzieren Sie mehrere Schrägstriche. Hinweis Dieser Wert ist ab Windows 11 (SDK Version 10.0.22000.194) verfügbar.

[out] ppszPathOut

Die Adresse eines Zeigers auf einen Puffer, der, wenn diese Funktion erfolgreich zurückgegeben wird, 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 funktion LocalFree aufgerufen wird. Dieser Wert kann nicht NULL-werden.

Rückgabewert

Wenn diese Funktion erfolgreich ist, wird S_OKzurückgegeben. Andernfalls wird ein HRESULT- Fehlercode zurückgegeben.

Bemerkungen

Diese Funktion unterstützt die folgenden alternativen Pfadformulare:

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

Diese Funktion konvertiert schräge Schrägstriche (/) nicht in Schrägstriche (\). Bei nicht vertrauenswürdigen Eingaben kann diese Funktion nicht allein verwendet werden, um Pfade in ein Formular zu konvertieren, das mit anderen Pfaden für Unterpfade oder Identität verglichen werden kann. Aufrufer, die diese Möglichkeit benötigen, sollten vor der Verwendung dieser Funktion in Umgekehrte Schrägstriche konvertiert werden.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 8 [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2012 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	pathcch.h
Library	Pathcch.lib

Freigeben über