Función PathCanonicalizeA (shlwapi.h)

Artículo
11/20/2024

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

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

Sintaxis

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

Parámetros

[out] pszBuf

Tipo: LPTSTR de

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 de

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 de

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

Observaciones

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 quita 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 contiene solo 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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000 Professional, Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	shlwapi.h
biblioteca de	Shlwapi.lib
DLL de	Shlwapi.dll (versión 4.71 o posterior)

Compartir a través de