Función UrlCanonicalizeA (shlwapi.h)
Convierte una cadena de dirección URL en formato canónico.
Sintaxis
LWSTDAPI UrlCanonicalizeA(
[in] PCSTR pszUrl,
[out] PSTR pszCanonicalized,
[in, out] DWORD *pcchCanonicalized,
DWORD dwFlags
);
Parámetros
[in] pszUrl
Tipo: PCTSTR
Puntero a una cadena terminada en null de longitud máxima INTERNET_MAX_URL_LENGTH que contiene una cadena de dirección URL. Si la cadena no hace referencia a un archivo, debe incluir un esquema válido como "http://".
[out] pszCanonicalized
Tipo: PTSTR de
Puntero a un búfer que, cuando esta función vuelve correctamente, recibe la dirección URL convertida como una cadena terminada en NULL.
[in, out] pcchCanonicalized
Tipo: DWORD* de
Puntero a un valor que, en la entrada, se establece en el número de caracteres del búfer de pszCanonicalized.
dwFlags
Tipo: DWORD de
Marcas que especifican cómo se convierte la dirección URL en formato canónico. Se pueden combinar las marcas siguientes.
URL_UNESCAPE (0x10000000)
Quite el escape de las secuencias de escape que contengan las direcciones URL, con dos excepciones. Las secuencias de escape de "?" y "#" no están sin escape. Si también se establece una de las marcas de URL_ESCAPE_XXX, las dos direcciones URL se desenrutan primero, luego se combinan y luego se escapan.
URL_ESCAPE_UNSAFE (0x20000000)
Reemplace caracteres no seguros por sus secuencias de escape. Los caracteres no seguros son los caracteres que se pueden modificar durante el transporte a través de Internet e incluyen los caracteres (<, >, ", #, {, }, |, , ^, [, ], y '). Esta marca se aplica a todas las direcciones URL, incluidas las direcciones URL opacas.
URL_PLUGGABLE_PROTOCOL (0x40000000)
Combine direcciones URL con protocolos conectables definidos por el cliente, según la especificación W3C. Esta marca no se aplica a protocolos estándar como ftp, http, gopher, etc. Si se establece esta marca, urlCombine no simplifica las direcciones URL, por lo que no es necesario establecer también URL_DONT_SIMPLIFY.
URL_ESCAPE_SPACES_ONLY (0x04000000)
Reemplace solo los espacios por secuencias de escape. Esta marca tiene prioridad sobre URL_ESCAPE_UNSAFE, pero no se aplica a direcciones URL opacas.
URL_DONT_SIMPLIFY (0x08000000)
Trate "/./" y "/.. /" en una cadena de dirección URL como caracteres literales, no como abreviada para la navegación. Vea comentarios para obtener más información.
URL_NO_META (0x08000000)
Se define para que sea igual que URL_DONT_SIMPLIFY.
URL_ESCAPE_PERCENT (0x00001000)
Convierta cualquier aparición de "%" en su secuencia de escape.
URL_ESCAPE_AS_UTF8 (0x00040000)
Windows 7 y versiones posteriores. Codifique por porcentaje todos los caracteres no ASCII como equivalentes UTF-8.
Valor devuelto
Tipo: HRESULT
Si esta función se ejecuta correctamente, devuelve S_OK. De lo contrario, devuelve un hrESULT código de error.
Observaciones
Esta función realiza tareas como reemplazar caracteres no seguros por sus secuencias de escape y secuencias de contracción como ".....".
Si una cadena de dirección URL contiene "/.. /" o "/./", UrlCanonicalize trata los caracteres como indica la navegación en la jerarquía de direcciones URL. La función simplifica las direcciones URL antes de combinarlas. Por ejemplo, "/hello/cruel/.. /world" se simplifica a "/hello/world". Las excepciones a este comportamiento predeterminado se producen en estos casos:
- Si la marca URL_DONT_SIMPLIFY está establecida en dwFlags, la función no simplifica las direcciones URL. En este caso, "/hello/cruel/.. /world" se deja tal como está.
- Si es "/.. /" o "/./" es el primer segmento de la ruta de acceso (por ejemplo, "http://domain/../path1/path2/file.htm"), UrlCanonicalize genera la ruta de acceso exactamente como era entrada.
Nota
El encabezado shlwapi.h define UrlCanonicalize como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Windows 2000 Professional, Windows XP [solo aplicaciones de escritorio] |
| servidor mínimo admitido | Windows 2000 Server [solo aplicaciones de escritorio] |
| de la plataforma de destino de |
Windows |
| encabezado de |
shlwapi.h |
| biblioteca de |
Shlwapi.lib |
| DLL de |
Shlwapi.dll (versión 5.0 o posterior) |