Función PathCanonicalizeA (shlwapi.h)

Simplifica una ruta de acceso quitando elementos de navegación como "." y ".." para generar una ruta de acceso directa y bien formada.

Nota El uso incorrecto de esta función puede provocar una saturación del búfer. Se recomienda usar la función PathCchCanonicalize o PathCchCanonicalizeEx más segura en su lugar.

 

Sintaxis

BOOL PathCanonicalizeA(
  [out] LPSTR  pszBuf,
  [in]  LPCSTR pszPath
);

Parámetros

[out] pszBuf

Tipo: LPTSTR

Puntero a una cadena que recibe la ruta de acceso canónica. Debe establecer el tamaño de este búfer en MAX_PATH para asegurarse de que es lo suficientemente grande como para contener la cadena devuelta.

[in] pszPath

Tipo: LPCTSTR

Puntero a una cadena terminada en null de longitud máxima MAX_PATH que contiene la ruta de acceso que se va a canónico.

Valor devuelto

Tipo: BOOL

Devuelve TRUE si se ha calculado un resultado y el contenido del búfer de salida lpszDst es válido. Devuelve FALSE de lo contrario, y el contenido del búfer al que apunta lpszDst no es válido. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Esta función permite al usuario especificar qué quitar de una ruta de acceso insertando secuencias de caracteres especiales en la ruta de acceso. La secuencia ".." indica que se va a quitar un segmento de ruta de acceso de la posición actual al segmento de ruta de acceso anterior. La secuencia "." indica que se omite el siguiente segmento de ruta de acceso al siguiente segmento de ruta de acceso. No se puede quitar el segmento raíz de la ruta de acceso.

Si hay más secuencias ".." de las que hay segmentos de ruta de acceso, la función devuelve TRUE y el contenido del búfer al que apunta lpszDst solo contiene la raíz, "".

Ejemplos

#include <windows.h>
#include <iostream>
#include "Shlwapi.h"

using namespace std;

int main( void )
{
// Path_1 destination buffer.
char buffer_1[MAX_PATH] = "JustABufferToHoldTheCanonicalizedPathForAnExample";
char *lpStr1;
lpStr1 = buffer_1;

// Path_2 to be Canonicalized.
char buffer_2[ ] = "A:\\name_1\\.\\name_2\\..\\name_3";
char *lpStr2;
lpStr2 = buffer_2;

// Path_3 to be Canonicalized.
char buffer_3[ ] = "A:\\name_1\\..\\name_2\\.\\name_3";
char *lpStr3;
lpStr3 = buffer_3;

// Path_4 to be Canonicalized.
char buffer_4[ ] = "A:\\name_1\\name_2\\.\\name_3\\..\\name_4";
char *lpStr4;
lpStr4 = buffer_4;

// Path_5 to be Canonicalized.
char buffer_5[ ] = "A:\\name_1\\.\\name_2\\.\\name_3\\..\\name_4\\..";
char *lpStr5;
lpStr5 = buffer_5;

// Path_6 to be Canonicalized.
char buffer_6[ ] = "C:\\..";
char *lpStr6;
lpStr6 = buffer_6;

cout << "The un-canonicalized path 2 is : " << lpStr2
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr2)
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

cout << "\nThe un-canonicalized path 3 is : " << lpStr3
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr3)
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

cout << "\nThe un-canonicalized path 4 is : " << lpStr4
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr4)
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

cout << "\nThe un-canonicalized path 5 is : " << lpStr5
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr5) 
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

cout << "\nThe un-canonicalized path 6 is : " << lpStr6
     << "\nThe return value is            : " 
     << PathCanonicalize(lpStr1,lpStr6)
     << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;
}
OUTPUT:
---------
The un-canonicalized path 2 is : A:\name_1\.\name_2\..\name_3
The return value is            : 1
The canonicalized path 1 is    : A:\name_1\name_3

The un-canonicalized path 3 is : A:\name_1\..\name_2\.\name_3
The return value is            : 1
The canonicalized path 1 is    : A:\name_2\name_3

The un-canonicalized path 4 is : A:\name_1\name_2\.\name_3\..\name_4
The return value is            : 1
The canonicalized path 1 is    : A:\name_1\name_2\name_4

The un-canonicalized path 5 is : A:\name_1\.\name_2\.\name_3\..\name_4\..
The return value is            : 1
The canonicalized path 1 is    : A:\name_1\name_2

The un-canonicalized path 6 is : C:\..
The return value is            : 1
The canonicalized path 1 is    : C:\

Nota:

El encabezado shlwapi.h define PathCanonicalize 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)