Función PathFindNextComponentA (shlwapi.h)

Analiza una ruta de acceso y devuelve la parte de esa ruta de acceso que sigue a la primera barra diagonal inversa.

Sintaxis

LPCSTR PathFindNextComponentA(
  [in] LPCSTR pszPath
);

Parámetros

[in] pszPath

Tipo: PTSTR

Puntero a una cadena terminada en null que contiene la ruta de acceso que se va a analizar. Esta cadena no debe tener más de MAX_PATH caracteres, además del carácter nulo de terminación. Los componentes de ruta de acceso se delimitan por barras diagonales inversas. Por ejemplo, la ruta de acceso "c:\path1\path2\file.txt" tiene cuatro componentes: c:, path1, path2 y file.txt.

Valor devuelto

Tipo: PTSTR

Devuelve un puntero a una cadena terminada en null que contiene la ruta de acceso truncada.

Si pszPath apunta al último componente de la ruta de acceso, esta función devuelve un puntero al carácter nulo de terminación.

Si pszPath apunta al carácter nulo de terminación o si se produce un error en la llamada, esta función devuelve NULL.

Comentarios

PathFindNextComponent recorre una cadena de ruta de acceso hasta que encuentra una barra diagonal inversa ("\"), omite todo hasta ese punto, incluida la barra diagonal inversa, y devuelve el resto de la ruta de acceso. Por lo tanto, si una ruta de acceso comienza con una barra diagonal inversa (como \path1\path2), la función simplemente quita la barra diagonal inversa inicial y devuelve el resto (path1\path2).

Ejemplos

La siguiente aplicación de consola simple pasa varias cadenas a PathFindNextComponent para demostrar lo que la función reconoce como un componente de ruta de acceso y mostrar lo que se devuelve. Para ejecutar este código en Visual Studio, debe vincular a Shlwapi.lib y definir UNICODE en los comandos del preprocesador en la configuración del proyecto.

#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

Nota

El encabezado shlwapi.h define PathFindNextComponent como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional, Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	shlwapi.h
Library	Shlwapi.lib
Archivo DLL	Shlwapi.dll (versión 4.71 o posterior)