Función PathCchCanonicalizeEx (pathcch.h)

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

Esta función difiere de PathCchCanonicalize en que permite construir una ruta final más larga.

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, PathCchCanonicalize o PathAllocCanonicalize se debe usar en lugar de PathCanonicalize para evitar la posibilidad de que se supere un búfer.

Sintaxis

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

Parámetros

[out] pszPathOut

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

[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 es NULL, 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.

[in] dwFlags

Una o varias de las marcas siguientes:

Value Significado
PATHCCH_NONE
0x0000000
No permita la construcción de rutas \\?\ (es decir, rutas de acceso largas) más largas que MAX_PATH .
PATHCCH_ALLOW_LONG_PATHS
0x00000001
Permita la creación de rutas \\?\ más largas que MAX_PATH . Tenga en cuenta que cchPathOut debe ser mayor que MAX_PATH . Si no es así, se omite esta marca.
PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS
0x00000002
Obliga a la API a tratar al autor de la llamada como ruta de acceso larga habilitada, independientemente del estado habilitado para el nombre largo del proceso. Esta opción solo se puede usar cuando se especifica PATHCCH_ALLOW_LONG_PATHS y no se puede usar con PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS.

Nota Este valor está disponible a partir de Windows 10, versión 1703.

PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS
0x00000004
Obliga a la API a tratar al autor de la llamada mientras la ruta de acceso esté deshabilitada, independientemente del estado habilitado del nombre largo del proceso. Esta opción solo se puede usar cuando se especifica PATHCCH_ALLOW_LONG_PATHS y no se puede usar con PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS.

Nota Este valor está disponible a partir de Windows 10, versión 1703.

PATHCCH_DO_NOT_NORMALIZE_SEGMENTS
0x00000008
Deshabilita la normalización de segmentos de ruta de acceso que incluye la eliminación de puntos y espacios finales. Esto permite el acceso a las rutas de acceso que bloqueará la normalización de rutas de acceso win32.

Nota Este valor está disponible a partir de Windows 10, versión 1703.

PATHCCH_ENSURE_IS_EXTENDED_LENGTH_PATH
0x00000010
Convierte la ruta de acceso de entrada en el formulario de ruta de acceso del dispositivo DOS de longitud extendida (con el prefijo \\?\ ) si aún no está en ese formulario. Esto permite el acceso a las rutas de acceso que, de lo contrario, no son direccionables debido a las reglas de normalización de Win32 (que pueden quitar los puntos finales y los espacios) y las limitaciones de longitud de ruta de acceso. Esta opción implica el mismo comportamiento de PATHCCH_DO_NOT_NORMALIZE_SEGMENTS.

Nota Este valor está disponible a partir de Windows 10, versión 1703.

PATHCCH_ENSURE_TRAILING_SLASH
0x00000020
Al combinar o normalizar una ruta de acceso, asegúrese de que hay una barra diagonal inversa final.

Nota Este valor está disponible a partir de Windows 10, versión 1703.

Valor devuelto

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

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 tiene más de PATHCCH_MAX_CCH caracteres o, si no se establece la marca de PATHCCH_ALLOW_LONG_PATHS , 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 [| de aplicaciones de escritorio Aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2012 [| de aplicaciones de escritorio Aplicaciones para UWP]
Plataforma de destino Windows
Encabezado pathcch.h
Library Pathcch.lib

Consulte también

PathCchCanonicalize