Función PathAllocCanonicalize (pathcch.h)

Artículo
02/21/2025

Convierte una cadena de ruta de acceso en una forma canónica.

Esta función difiere de PathCchCanonicalize y PathCchCanonicalizeEx en que devuelve el resultado en el montón. Esto significa que el autor de la llamada no tiene que declarar el tamaño de la cadena devuelta y reduce el uso de la pila.

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

Nota Esta función, PathCchCanonicalize, o PathCchCanonicalizeEx, debe usarse en lugar de PathCanonicalize.

Sintaxis

WINPATHCCHAPI HRESULT PathAllocCanonicalize(
  [in]  PCWSTR pszPathIn,
  [in]  ULONG  dwFlags,
  [out] PWSTR  *ppszPathOut
);

Parámetros

[in] pszPathIn

Puntero a un búfer que contiene la cadena original. Este valor no se puede null.

[in] dwFlags

Una o varias de las marcas siguientes:

Valor	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 .
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 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_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 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 los 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.
PATHCCH_CANONICALIZE_SLASHES 0x00000040	Convierta barras diagonales a barras diagonales inversas y contraiga varias barras diagonales. Nota Este valor está disponible a partir de Windows 11 (SDK versión 10.0.22000.194).

[out] ppszPathOut

La dirección de un puntero a un búfer que, cuando esta función vuelve correctamente, recibe la cadena de ruta de acceso canónica. Es responsabilidad del autor de la llamada liberar este recurso, cuando ya no es necesario, llamando a la función LocalFree. Este valor no se puede null.

Valor devuelto

Si esta función se ejecuta correctamente, devuelve S_OK. De lo contrario, devuelve un hrESULT código de error.

Observaciones

Esta función admite estos formularios alternativos de ruta de acceso:

\\?\
\\?\\UNC\
\\?\Volume{guid}\

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.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 8 [aplicaciones de escritorio \| Aplicaciones para UWP]
servidor mínimo admitido	Windows Server 2012 [aplicaciones de escritorio \| Aplicaciones para UWP]
de la plataforma de destino de	Windows
encabezado de	pathcch.h
biblioteca de	Pathcch.lib

Compartir a través de