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 vuelve 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:

Valor	Significado
PATHCCH_NONE 0x0000000	No permita la construcción de rutas \\?\ (es decir, rutas largas) más largas que MAX_PATH .
PATHCCH_ALLOW_LONG_PATHS 0x00000001	Permita la creación de rutas de acceso \\?\ 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 la 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 como la ruta de acceso larga 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 quitar puntos y espacios finales. Esto permite el acceso a las rutas de acceso que bloqueará la normalización de la ruta 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 se pueden direccionar debido a las reglas de normalización de Win32 (que pueden quitar los puntos y espacios finales) y las limitaciones de longitud de la 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 haya 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 pero no limitado a lo siguiente.

Código devuelto	Descripción
E_INVALIDARG	El valor 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 inmediatamente anterior. La cadena "." indica que se omite 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 puntos 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 puntos 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

Requisito	Value
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

PathCchCanonicalize