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".
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 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 |
|---|---|
|
El valor cchPathOut es mayor que PATHCCH_MAX_CCH. |
|
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. |
|
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 |