PathCchCanonicalize-Funktion (pathcch.h)

  • Artikel

Konvertiert eine Pfadzeichenfolge in eine kanonische Form.

Diese Funktion unterscheidet sich von PathCchCanonicalizeEx darin, dass Sie auf einen endgültigen Pfad der Länge MAX_PATH beschränkt sind.

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, PathCchCanonicalizeEx oder PathAllocCanonicalize , sollte anstelle von PathCanonicalize verwendet werden, um die Möglichkeit eines Pufferüberlaufs zu verhindern.

Syntax

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

Parameter

[out] pszPathOut

Ein Zeiger auf einen Puffer, der die kanonische 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 auf eine leere Zeichenfolge zeigt oder zu einer leeren Zeichenfolge führt, sobald die Elemente "." und ".." entfernt wurden, wird ein einzelner umgekehrter Schrägstrich in den Puffer kopiert, auf den pszPathOut verweist.

Rückgabewert

Wenn diese Funktion erfolgreich ist, wird S_OK zurückgegeben. Andernfalls wird ein HRESULT-Code zurückgegeben, einschließlich des folgenden.

Rückgabecode Beschreibung
E_INVALIDARG
 Der cchPathOut-Wert ist größer als PATHCCH_MAX_CCH.
PATHCCH_E_FILENAME_TOO_LONG
 Ein Pfadsegment überschreitet 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

   
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

PathCchCanonicalizeEx