Función UrlCanonicalizeA (shlwapi.h)
Convierte una cadena de dirección URL al 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
Puntero a un búfer que, cuando esta función devuelve correctamente, recibe la dirección URL convertida como una cadena terminada en null.
[in, out] pcchCanonicalized
Tipo: DWORD*
Puntero a un valor que, en la entrada, se establece en el número de caracteres del búfer pszCanonicalized .
dwFlags
Tipo: DWORD
Marcas que especifican cómo se convierte la dirección URL en forma canónica. Se pueden combinar las marcas siguientes.
URL_UNESCAPE (0x10000000)
Anulación de escape de las secuencias de escape que contienen las direcciones URL, con dos excepciones. No se elimina el escape de las secuencias de escape de "?" y "#". Si también se establece una de las marcas de URL_ESCAPE_XXX, las dos direcciones URL se desenrutan primero y, a continuación, se combinan y, a continuación, se aplican caracteres de escape.
URL_ESCAPE_UNSAFE (0x20000000)
reemplaza los caracteres no seguros por sus secuencias de escape. Los caracteres no seguros son aquellos 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 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)
solo reemplaza 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)
trata "/./" y "/../" en una cadena de dirección URL como caracteres literales, no como abreviatura de 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)
convierte 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 sus equivalentes UTF-8.
Valor devuelto
Tipo: HRESULT
Si esta función se realiza correctamente, devuelve S_OK. De lo contrario, devuelve un código de error de HRESULT.
Comentarios
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 ha simplificado a "/hello/world". Las excepciones a este comportamiento predeterminado se producen en estos casos:
- Si la marca URL_DONT_SIMPLIFY se establece en dwFlags, la función no simplifica las direcciones URL. En este caso, "/hello/cruel/.. /world" se deja tal y 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 igual que la 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 Convenciones para prototipos de función.
Requisitos
| Cliente mínimo compatible | Windows 2000 Professional, Windows XP [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows 2000 Server [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | shlwapi.h |
| Library | Shlwapi.lib |
| Archivo DLL | Shlwapi.dll (versión 5.0 o posterior) |