Função PathFindNextComponentW (shlwapi.h)

Analisa um caminho e retorna a parte desse caminho que segue a primeira barra invertida.

Sintaxe

LPCWSTR PathFindNextComponentW(
  [in] LPCWSTR pszPath
);

Parâmetros

[in] pszPath

Tipo: PTSTR

Um ponteiro para uma cadeia de caracteres terminada em nulo que contém o caminho a ser analisado. Essa cadeia de caracteres não deve ter mais de MAX_PATH caracteres, além do caractere nulo de terminação. Os componentes de caminho são delimitados por barras invertidas. Por exemplo, o caminho "c:\path1\path2\file.txt" tem quatro componentes: c:, path1, path2 e file.txt.

Valor retornado

Tipo: PTSTR

Retorna um ponteiro para uma cadeia de caracteres terminada em nulo que contém o caminho truncado.

Se pszPath apontar para o último componente no caminho, essa função retornará um ponteiro para o caractere nulo de terminação.

Se pszPath apontar para o caractere nulo de terminação ou se a chamada falhar, essa função retornará NULL.

Comentários

PathFindNextComponent percorre uma cadeia de caracteres de caminho até encontrar uma barra invertida ("\"), ignora tudo até esse ponto, incluindo a barra invertida, e retorna o restante do caminho. Portanto, se um caminho começar com uma barra invertida (como \path1\path2), a função simplesmente removerá a barra invertida inicial e retornará o restante (path1\path2).

Exemplos

O aplicativo de console simples a seguir passa várias cadeias de caracteres para PathFindNextComponent para demonstrar o que a função reconhece como um componente de caminho e para mostrar o que é retornado. Para executar esse código no Visual Studio, você deve vincular a Shlwapi.lib e definir UNICODE nos comandos de pré-processador nas configurações do projeto.

#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

Observação

O cabeçalho shlwapi.h define PathFindNextComponent como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Cliente mínimo com suporte	Windows 2000 Professional, Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	shlwapi.h
Biblioteca	Shlwapi.lib
DLL	Shlwapi.dll (versão 4.71 ou posterior)