Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

PathFindNextComponent function

Parses a path and returns the portion of that path that follows the first backslash.

Syntax


PTSTR PathFindNextComponent(
  _In_  PTSTR pszPath
);

Parameters

pszPath [in]

Type: PTSTR

A pointer to a null-terminated string that contains the path to parse. This string must not be longer than MAX_PATH characters, plus the terminating null character. Path components are delimited by backslashes. For instance, the path "c:\path1\path2\file.txt" has four components: c:, path1, path2, and file.txt.

Return value

Type: PTSTR

Returns a pointer to a null-terminated string that contains the truncated path.

If pszPath points to the last component in the path, this function returns a pointer to the terminating null character.

If pszPath points to the terminating null character or if the call fails, this function returns NULL.

Remarks

PathFindNextComponent walks a path string until it encounters a backslash ("\\"), ignores everything up to that point including the backslash, and returns the rest of the path. Therefore, if a path begins with a backslash (such as \path1\path2), the function simply removes the initial backslash and returns the rest (path1\path2).

Examples

The following simple console application passes various strings to PathFindNextComponent to demonstrate what the function recognizes as a path component and to show what is returned. To run this code in Visual Studio, you must link to Shlwapi.lib and define UNICODE in the preprocessor commands in the project settings.



#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

Requirements

Minimum supported client

Windows 2000 Professional, Windows XP [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Shlwapi.h

Library

Shlwapi.lib

DLL

Shlwapi.dll (version 4.71 or later)

Unicode and ANSI names

PathFindNextComponentW (Unicode) and PathFindNextComponentA (ANSI)

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.