PathFindNextComponentW-Funktion (shlwapi.h)

Artikel
11/20/2024

Analysiert einen Pfad und gibt den Teil dieses Pfads zurück, der dem ersten umgekehrten Schrägstrich folgt.

Syntax

LPCWSTR PathFindNextComponentW(
  [in] LPCWSTR pszPath
);

Parameter

[in] pszPath

Typ: PTSTR-

Ein Zeiger auf eine mit Null beendete Zeichenfolge, die den Zu analysierenden Pfad enthält. Diese Zeichenfolge darf nicht länger als MAX_PATH Zeichen und das endende NULL-Zeichen sein. Pfadkomponenten werden durch umgekehrte Schrägstriche getrennt. Beispielsweise hat der Pfad "c:\path1\path2\file.txt" vier Komponenten: c:, path1, path2 und file.txt.

Rückgabewert

Typ: PTSTR-

Gibt einen Zeiger auf eine mit Null beendete Zeichenfolge zurück, die den abgeschnittenen Pfad enthält.

Wenn pszPath auf die letzte Komponente im Pfad verweist, gibt diese Funktion einen Zeiger auf das endende Nullzeichen zurück.

Wenn pszPath auf das endende Nullzeichen verweist oder wenn der Aufruf fehlschlägt, gibt diese Funktion NULL-zurück.

Bemerkungen

PathFindNextComponent eine Pfadzeichenfolge durchläuft, bis ein umgekehrter Schrägstrich ("\") auftritt, ignoriert alles bis zu diesem Punkt einschließlich des umgekehrten Schrägstrichs und gibt den Rest des Pfads zurück. Wenn ein Pfad daher mit einem umgekehrten Schrägstrich (z. B. \path1\path2) beginnt, entfernt die Funktion einfach den anfänglichen umgekehrten Schrägstrich und gibt den Rest zurück (Pfad1\Pfad2).

Beispiele

Die folgende einfache Konsolenanwendung übergibt verschiedene Zeichenfolgen an PathFindNextComponent, um zu veranschaulichen, was die Funktion als Pfadkomponente erkennt und zeigt, was zurückgegeben wird. Um diesen Code in Visual Studio auszuführen, müssen Sie eine Verknüpfung mit Shlwapi.lib herstellen und UNICODE in den Präprozessorbefehlen in den Projekteinstellungen definieren.


#include <windows.h>
#include <iostream>
#include <shlwapi.h>

#pragma comment(lib, "shlwapi.lib")     // Link to this file.

int main()
{
    using namespace std;
   
    PCWSTR path = L"c:\\path1\\path2\\file.txt";
 
    // This loop passes a full path to PathFindNextComponent and feeds the 
    // results of that call back into the function until the entire path has
    // been walked.
    while (path)
    {
        PCWSTR oldPath = path;
        path = PathFindNextComponent(path);
 
        // The path variable pointed to the terminating null character.
        if (path == NULL)
        {
            wcout << L"The terminating null character returns NULL\n\n";
        }
        // The path variable pointed to a path with only one component.
		else if (*path == 0)
        {
            wcout << L"The path " << oldPath 
                  << L" returns a pointer to the terminating null character\n"; 
        }
        else 
        {
            wcout << L"The path " << oldPath << L" returns " << path << L"\n";
        }
    }
 
    // These calls demonstrate the results of different path forms.
    // Note that where those paths begin with backslashes, those
    // backslashes are merely stripped away and the entire path is returned.

    PCWSTR path1 = L"\\path1";

    wcout << L"The path " << path1 << L" returns " 
          << PathFindNextComponent(path1);
        
    PCWSTR path2 = L"\\path1\\path2";

    wcout << L"\nThe path " << path2 << L" returns "
          << PathFindNextComponent(path2);
        
    PCWSTR path3 = L"path1\\path2";
 
    wcout << L"\nThe path " << path3 << L" returns "
          << PathFindNextComponent(path3);
 
    wcout << L"\nThe path " << L"c:\\file.txt" << L" returns "
          << PathFindNextComponent(L"c:\\file.txt");
 
    return 0;
}

OUTPUT:
===========
The path c:\path1\path2\file.txt returns path1\path2\file.txt
The path path1\path2\file.txt returns path2\file.txt
The path path2\file.txt returns file.txt
The path file.txt returns a pointer to the terminating null character
The terminating null character returns NULL

The path \path1 returns path1
The path \path1\path2 returns path1\path2
The path path1\path2 returns path2
The path c:\file.txt returns file.txt

Anmerkung

Der Header "shlwapi.h" definiert PathFindNextComponent als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 2000 Professional, Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	shlwapi.h
Library	Shlwapi.lib
DLL-	Shlwapi.dll (Version 4.71 oder höher)

Freigeben über