Función InternetCanonicalizeUrlA (wininet.h)
Convierte en canónica una dirección URL, que incluye la conversión de espacios y caracteres no seguros en secuencias de escape.
Sintaxis
BOOL InternetCanonicalizeUrlA(
[in] LPCSTR lpszUrl,
[out] LPSTR lpszBuffer,
[in, out] LPDWORD lpdwBufferLength,
[in] DWORD dwFlags
);
Parámetros
[in] lpszUrl
Puntero a la cadena que contiene la dirección URL que se va a canónico.
[out] lpszBuffer
Puntero al búfer que recibe la dirección URL canónica resultante.
[in, out] lpdwBufferLength
Puntero a una variable que contiene el tamaño, en caracteres, del búfer lpszBuffer . Si la función se ejecuta correctamente, este parámetro recibe el número de caracteres copiados realmente en el búfer lpszBuffer , que no incluye el carácter nulo de terminación. Si se produce un error en la función, este parámetro recibe el tamaño necesario del búfer, en caracteres, que incluye el carácter nulo de terminación.
[in] dwFlags
Controla la canonización. Si no se especifican marcas, la función convierte todos los caracteres no seguros y las secuencias meta (como .,\ .., y ...) en secuencias de escape. Este parámetro puede ser uno de los valores siguientes.
| Valor | Significado |
|---|---|
|
No codifica ni descodifica caracteres después de "#" o "?", y no quita el espacio en blanco final después de "?". Si no se especifica este valor, se codifica toda la dirección URL y se quita el espacio en blanco final. |
|
Convierte todas las secuencias %XX en caracteres, incluidas las secuencias de escape, antes de analizar la dirección URL. |
|
Codifica los signos de porcentaje encontrados. De forma predeterminada, los signos de porcentaje no están codificados. Este valor está disponible en Microsoft Internet Explorer 5 y versiones posteriores. |
|
Codifica solo espacios. |
|
No convierte caracteres no seguros en secuencias de escape. |
|
No quita las secuencias meta (como "." y "..") de la dirección URL. |
Valor devuelto
Devuelve TRUE si es correcto o FALSE en caso contrario. Para obtener información ampliada de los errores, llame a la función GetLastError. Entre los posibles errores se incluyen los siguientes.
| Código devuelto | Descripción |
|---|---|
|
No se pudo canonizar la dirección URL. |
|
La dirección URL canónica es demasiado grande para caber en el búfer proporcionado. El parámetro lpdwBufferLength se establece en el tamaño, en bytes, del búfer necesario para contener la dirección URL canónica. |
|
El formato de la dirección URL no es válido. |
|
Hay un parámetro de cadena, búfer, tamaño de búfer o marcas no válidos. |
Comentarios
En Internet Explorer 4.0 y versiones posteriores, InternetCanonicalizeUrl siempre funciona como si se establece la marca ICU_BROWSER_MODE . Las aplicaciones cliente que deben canónicar toda la dirección URL deben usar CoInternetParseUrl (con la acción PARSE_CANONICALIZE y la marca URL_ESCAPE_UNSAFE) o UrlCanonicalize.
InternetCanonicalizeUrl siempre codifica de forma predeterminada, incluso si se ha especificado la marca ICU_DECODE . Para descodificar sin volver a codificar, use ICU_DECODE | ICU_NO_ENCODE. Si se usa la marca ICU_DECODE sin ICU_NO_ENCODE, la dirección URL se descodifica antes de analizarla; Los caracteres no seguros se vuelven a codificar después del análisis. Esta función controla esquemas de protocolo arbitrarios, pero para ello debe realizar inferencias del juego de caracteres no seguro.
Las aplicaciones que llaman a InternetCanonicalizeUrl cuando se usa Internet Explorer 3.0 (o al establecer la marca ICU_ENCODE_PERCENT para Internet Explorer 5 y versiones posteriores) deben realizar un seguimiento del uso de esta función en una dirección URL determinada. Si los caracteres no seguros de una dirección URL se han convertido en secuencias de escape, el uso de InternetCanonicalizeUrl de nuevo en la dirección URL (sin marcas) hace que las secuencias de escape se conviertan en otra secuencia de escape. Por ejemplo, un espacio en blanco en una dirección URL se convertirá en la secuencia de escape %20. Si se llama a InternetCanonicalizeUrl de nuevo en la dirección URL, la secuencia de escape %20 se convertirá en la secuencia de escape %2520, ya que el signo % es un carácter no seguro reservado para secuencias de escape y se reemplaza por la función por la secuencia de escape %25.
Al igual que todos los demás aspectos de la API de WinINet, esta función no se puede llamar de forma segura desde DllMain ni desde los constructores y destructores de objetos globales.
Nota:
El encabezado wininet.h define InternetCanonicalizeUrl 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 [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows 2000 Server [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | wininet.h |
| Library | Wininet.lib |
| Archivo DLL | Wininet.dll |