Función PathCchCanonicalize (pathcch.h)

  • Artículo

Convierte una cadena de ruta de acceso en un formulario canónico.

Esta función difiere de PathCchCanonicalizeEx en que está restringido a una ruta de acceso final de longitud MAX_PATH.

Esta función difiere de PathAllocCanonicalize en que el autor de la llamada debe declarar el tamaño de la cadena devuelta, que se almacena en la pila.

Esta función difiere de PathCanonicalize en que acepta rutas de acceso con prefijos "\", "\?" y "\?\UNC".

Nota Esta función, PathCchCanonicalizeEx o PathAllocCanonicalize se debe usar en lugar de PathCanonicalize para evitar que se supere un búfer.

Sintaxis

WINPATHCCHAPI HRESULT PathCchCanonicalize(
  [out] PWSTR  pszPathOut,
  [in]  size_t cchPathOut,
  [in]  PCWSTR pszPathIn
);

Parámetros

[out] pszPathOut

Puntero a un búfer que, cuando esta función devuelve correctamente, recibe la cadena de ruta de acceso canónica.

[in] cchPathOut

Tamaño del búfer al que apunta pszPathOut, en caracteres.

[in] pszPathIn

Puntero a la cadena de ruta de acceso original. Si este valor apunta a una cadena vacía o da como resultado una cadena vacía una vez que se quitan los elementos "." y ".." , se copia una sola barra diagonal inversa en el búfer al que apunta pszPathOut.

Valor devuelto

Si esta función se realiza correctamente, devuelve S_OK. De lo contrario, devuelve un código HRESULT , incluido lo siguiente.

Código devuelto Descripción
E_INVALIDARG
 El valor de cchPathOut es mayor que PATHCCH_MAX_CCH.
PATHCCH_E_FILENAME_TOO_LONG
 Un segmento de ruta de acceso supera el límite de longitud del segmento de ruta de acceso estándar de 256 caracteres.
E_OUTOFMEMORY
 La función no pudo asignar un búfer del tamaño necesario.

Comentarios

Esta función responde a las cadenas "." y ".." insertadas en una ruta de acceso. La cadena ".." indica que se va a quitar el segmento de ruta de acceso inmediatamente anterior. La cadena "." indica que se omitirá el siguiente segmento de ruta de acceso. Tenga en cuenta que no se puede quitar el segmento raíz de la ruta de acceso. Si hay más cadenas ".." de las que hay segmentos de ruta de acceso, la función devuelve S_OK y el búfer al que apunta pszPathOut contiene una sola barra diagonal inversa, "\".

Todos los períodos finales se quitan de la ruta de acceso, excepto cuando van precedidos por el carácter comodín "". En ese caso, se conserva un único punto después del carácter "", pero se quitan todos los demás períodos finales.

Si la ruta de acceso resultante es una unidad raíz ("x:"), se anexa una barra diagonal inversa ("x:\").

Esta función no convierte barras diagonales (/) en barras diagonales inversas (\). Con la entrada que no es de confianza, esta función no se puede usar para convertir rutas de acceso en un formulario que se pueda comparar con otras rutas de acceso para la subruta o la identidad. Los autores de llamadas que necesitan esa capacidad deben convertir hacia delante a barras diagonales inversas antes de usar esta función.

En los ejemplos siguientes se muestra el efecto de estas cadenas.

Cadena original Cadena canónica
C:\name_1\.\name_2\.. \name_3 C:\name_1\name_3
C:\name_1\.. \name_2\.\name_3 C:\name_2\name_3
C:\name_1\name_2\.\name_3\.. \name_4 C:\name_1\name_2\name_4
C:\name_1\.\name_2\.\name_3\.. \name_4\.. C:\name_1\name_2
C:\name_1\*... C:\name_1\*.
C:\.. C:\

Requisitos

   
Cliente mínimo compatible Windows 8 [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2012 [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino Windows
Encabezado pathcch.h
Library Pathcch.lib

Consulte también

PathCchCanonicalizeEx