PathCchCanonicalize-Funktion (pathcch.h)
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.
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 |
|---|---|
|
Der cchPathOut-Wert ist größer als PATHCCH_MAX_CCH. |
|
Ein Pfadsegment überschreitet die Standardlänge des Pfadsegments von 256 Zeichen. |
|
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 |