Função InternetCanonicalizeUrlA (wininet.h)
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 |
|---|---|
|
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. |
|
Converte todas as sequências %XX em caracteres, incluindo sequências de escape, antes que a URL seja analisada. |
|
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. |
|
Codifica apenas espaços. |
|
Não converte caracteres não seguros em sequências de escape. |
|
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 |
|---|---|
|
Não foi possível canonizar a URL. |
|
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. |
|
O formato da URL é inválido. |
|
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.
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 |