Função InternetCanonicalizeUrlA (wininet.h)

  • Artigo

Canonicaliza uma URL, que inclui a conversão de caracteres e espaços desprotegidos 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 canonizada.

[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 terminação.

[in] dwFlags

Controla a canonização. Se nenhum sinalizador for especificado, a função converterá todos os caracteres e sequências meta não seguros (como .,\ .., e ...) em sequências de escape. Esse parâmetro pode usar 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 %XX em caracteres, incluindo sequências de escape, antes que a URL seja analisada.
ICU_ENCODE_PERCENT
 Codifica todos os sinais de porcentagem encontrados. 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 retornado

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 canonizada é 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 canonizada.
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.

Comentários

Na Internet Explorer 4.0 e posterior, InternetCanonicalizeUrl sempre funciona como se o sinalizador 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 a Internet Explorer 3.0 (ou ao definir o sinalizador ICU_ENCODE_PERCENT para a 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.

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.

Nota 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 Os Serviços HTTP do Microsoft Windows (WinHTTP).
 

Observação

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 de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

   
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho wininet.h
Biblioteca Wininet.lib
DLL Wininet.dll

Confira também

Manipulando localizadores de recursos uniformes

Funções WinINet