Função InternetCanonicalizeUrlA (wininet.h)

Artigo
11/20/2024

Canoniza uma URL, que inclui a conversão de caracteres e espaços não seguros em sequências de escape.

Sintaxe

BOOL InternetCanonicalizeUrlA(
  [in]      LPCSTR  lpszUrl,
  [out]     LPSTR   lpszBuffer,
  [in, out] LPDWORD lpdwBufferLength,
  [in]      DWORD   dwFlags
);

Parâmetros

[in] lpszUrl

Um ponteiro para a cadeia de caracteres que contém a URL a ser canônica.

[out] lpszBuffer

Um ponteiro para o buffer que recebe a URL canônica resultante.

[in, out] lpdwBufferLength

Um ponteiro para uma variável que contém o tamanho, em caracteres, do buffer lpszBuffer. Se a função for bem-sucedida, esse parâmetro receberá o número de caracteres realmente copiados para o buffer lpszBuffer, que não inclui o caractere nulo de terminação. Se a função falhar, esse parâmetro receberá o tamanho necessário do buffer, em caracteres, que inclui o caractere nulo de encerramento.

[in] dwFlags

Controla a canonicalização. Se nenhum sinalizador for especificado, a função converterá todos os caracteres não seguros e meta sequências (como .,\ .., e ...) em sequências de escape. Esse parâmetro pode ser um dos valores a seguir.

Valor	Significado
ICU_BROWSER_MODE	Não codifica ou decodifica caracteres após "#" ou "?", e não remove o espaço em branco à direita após "?". Se esse valor não for especificado, toda a URL será codificada e o espaço em branco à direita será removido.
ICU_DECODE	Converte todas as sequências de %XX em caracteres, incluindo sequências de escape, antes que a URL seja analisada.
ICU_ENCODE_PERCENT	Codifica qualquer sinal de porcentagem encontrado. Por padrão, os sinais de porcentagem não são codificados. Esse valor está disponível no Microsoft Internet Explorer 5 e posterior.
ICU_ENCODE_SPACES_ONLY	Codifica apenas espaços.
ICU_NO_ENCODE	Não converte caracteres não seguros em sequências de escape.
ICU_NO_META	Não remove meta sequências (como "." e "..") da URL.

Valor de retorno

Retorna TRUE se tiver êxito ou false caso contrário. Para obter informações de erro estendidas, chame a função GetLastError. Os possíveis erros incluem o seguinte.

Código de retorno	Descrição
ERROR_BAD_PATHNAME	Não foi possível canonizar a URL.
ERROR_INSUFFICIENT_BUFFER	A URL canônica é muito grande para caber no buffer fornecido. O parâmetro lpdwBufferLength é definido como o tamanho, em bytes, do buffer necessário para manter a URL canônica.
ERROR_INTERNET_INVALID_URL	O formato da URL é inválido.
ERROR_INVALID_PARAMETER	Há um parâmetro de cadeia de caracteres, buffer, tamanho do buffer ou sinalizadores inválidos.

Observações

No Internet Explorer 4.0 e posterior, InternetCanonicalizeUrl sempre funciona como se o sinalizador de ICU_BROWSER_MODE estivesse definido. Os aplicativos cliente que devem canonizar toda a URL devem usar CoInternetParseUrl (com a ação PARSE_CANONICALIZE e o sinalizador URL_ESCAPE_UNSAFE) ou UrlCanonicalize.

InternetCanonicalizeUrl sempre codifica por padrão, mesmo que o sinalizador ICU_DECODE tenha sido especificado. Para decodificar sem reencodificação, use ICU_DECODE | ICU_NO_ENCODE. Se o sinalizador ICU_DECODE for usado sem ICU_NO_ENCODE, a URL será decodificada antes de ser analisada; os caracteres não seguros são codificados novamente após a análise. Essa função lida com esquemas de protocolo arbitrários, mas, para isso, deve fazer inferências do conjunto de caracteres não seguro.

Os aplicativos que chamam InternetCanonicalizeUrl ao usar o Internet Explorer 3.0 (ou ao definir o sinalizador ICU_ENCODE_PERCENT para o Internet Explorer 5 e posterior) devem acompanhar o uso dessa função em uma URL específica. Se caracteres não seguros em uma URL tiverem sido convertidos em sequências de escape, usar InternetCanonicalizeUrl novamente na URL (sem sinalizadores) fará com que as sequências de escape sejam convertidas em outra sequência de escape. Por exemplo, um espaço em branco em uma URL seria convertido na sequência de escape %20. Chamar InternetCanonicalizeUrl novamente na URL faria com que a sequência de escape %20 fosse convertida na sequência de escape %2520, pois o sinal de % é um caractere não seguro reservado para sequências de escape e é substituído pela função pela sequência de escape %25.

Assim como todos os outros aspectos da API WinINet, essa função não pode ser chamada com segurança de dentro do DllMain ou dos construtores e destruidores de objetos globais.

Observação WinINet não dá suporte a implementações de servidor. Além disso, ele não deve ser usado de um serviço. Para implementações ou serviços de servidor, use do Microsoft Windows HTTP Services (WinHTTP).

Nota

O cabeçalho wininet.h define InternetCanonicalizeUrl como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	wininet.h
biblioteca	Wininet.lib
de DLL	Wininet.dll

Consulte também

tratando de recursos uniformes

do WinINet Functions

Compartilhar via