Función InternetCanonicalizeUrlA (wininet.h)

  • Artículo

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
ICU_BROWSER_MODE
 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.
ICU_DECODE
 Convierte todas las secuencias %XX en caracteres, incluidas las secuencias de escape, antes de analizar la dirección URL.
ICU_ENCODE_PERCENT
 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.
ICU_ENCODE_SPACES_ONLY
 Codifica solo espacios.
ICU_NO_ENCODE
 No convierte caracteres no seguros en secuencias de escape.
ICU_NO_META
 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
ERROR_BAD_PATHNAME
 No se pudo canonizar la dirección URL.
ERROR_INSUFFICIENT_BUFFER
 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.
ERROR_INTERNET_INVALID_URL
 El formato de la dirección URL no es válido.
ERROR_INVALID_PARAMETER
 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 WinINet no admite implementaciones de servidor. Además, no se debe usar desde un servicio. En el caso de las implementaciones de servidor o los servicios, use Servicios HTTP de Microsoft Windows (WinHTTP).
 

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

Consulte también

Control de localizadores uniformes de recursos

Funciones de WinINet