Función InternetCanonicalizeUrlA (wininet.h)

Artículo
11/20/2024

Canónicamente una dirección URL, que incluye la conversión de caracteres y espacios 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 de lpszBuffer. Si la función se ejecuta correctamente, este parámetro recibe el número de caracteres copiados realmente en el búfer de 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 canónica. 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 siguientes valores.

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 de %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 los 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 se ejecuta correctamente o FALSE de lo contrario. Para obtener información de error extendida, 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 canónico 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.

Observaciones

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ónicoizar 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 la marca ICU_DECODE se usa sin ICU_NO_ENCODE, la dirección URL se descodifica antes de analizarse; 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 hacer inferencias del juego de caracteres no seguros.

Las aplicaciones que llaman a InternetCanonicalizeUrl al usar Internet Explorer 3.0 (o al establecer la marca de 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 se han convertido caracteres no seguros en una dirección URL 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. Llamar a InternetCanonicalizeUrl de nuevo en la dirección URL provocaría que la secuencia de escape %20 se convierta en la secuencia de escape %2520, porque el signo % es un carácter no seguro que está 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 Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000 Professional [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	wininet.h
biblioteca de	Wininet.lib
DLL de	Wininet.dll

Consulte también

control de localizadores uniformes de recursos

funciones winINet

Compartir a través de