Função UrlCanonicalizeW (shlwapi.h)

  • Artigo

Converte uma cadeia de caracteres de URL em forma canônica.

Sintaxe

LWSTDAPI UrlCanonicalizeW(
  [in]      PCWSTR pszUrl,
  [out]     PWSTR  pszCanonicalized,
  [in, out] DWORD  *pcchCanonicalized,
            DWORD  dwFlags
);

Parâmetros

[in] pszUrl

Tipo: PCTSTR

Um ponteiro para uma cadeia de caracteres terminada em nulo de comprimento máximo INTERNET_MAX_URL_LENGTH que contém uma cadeia de caracteres de URL. Se a cadeia de caracteres não fizer referência a um arquivo, ela deverá incluir um esquema válido, como "http://".

[out] pszCanonicalized

Tipo: PTSTR

Um ponteiro para um buffer que, quando essa função retorna com êxito, recebe a URL convertida como uma cadeia de caracteres terminada em nulo.

[in, out] pcchCanonicalized

Tipo: DWORD*

Um ponteiro para um valor que, na entrada, é definido como o número de caracteres no buffer pszCanonicalized .

dwFlags

Tipo: DWORD

Os sinalizadores que especificam como a URL é convertida em forma canônica. Os sinalizadores a seguir podem ser combinados.

URL_UNESCAPE (0x10000000)

Cancele o escape de todas as sequências de escape que as URLs contêm, com duas exceções. As sequências de escape para "?" e "#" não ficam sem escape. Se um dos sinalizadores de URL_ESCAPE_XXX também estiver definido, as duas URLs serão primeiro não escapadas, depois combinadas e, em seguida, escapadas.

URL_ESCAPE_UNSAFE (0x20000000)

substitua caracteres desprotegidos pelas suas sequências de escape. Caracteres não seguros são os caracteres que podem ser alterados durante o transporte pela Internet e incluem os caracteres (<, >, ", #, {, }, |, , ^, [, ]e '). Esse sinalizador se aplica a todas as URLs, incluindo URLs opacas.

URL_PLUGGABLE_PROTOCOL (0x40000000)

Combine URLs com protocolos conectáveis definidos pelo cliente, de acordo com a especificação do W3C. Esse sinalizador não se aplica a protocolos padrão, como FTP, HTTP, Gopher e assim por diante. Se esse sinalizador estiver definido, UrlCombine não simplificará as URLs, portanto, não será necessário definir também URL_DONT_SIMPLIFY.

URL_ESCAPE_SPACES_ONLY (0x04000000)

substitua apenas espaços por sequências de escape. Esse sinalizador tem precedência sobre URL_ESCAPE_UNSAFE, mas não se aplica a URLs opacas.

URL_DONT_SIMPLIFY (0x08000000)

Trate "/./" e "/../" em uma cadeia de caracteres de URL como caracteres literais, não como uma abreviação para navegação. Consulte Comentários para mais discussões.

URL_NO_META (0x08000000)

Definido como o mesmo que URL_DONT_SIMPLIFY.

URL_ESCAPE_PERCENT (0x00001000)

converta ocorrências de "%" em sua sequência de escape.

URL_ESCAPE_AS_UTF8 (0x00040000)

Windows 7 e posterior. Codificar por porcentagem todos os caracteres não ASCII como seus equivalentes UTF-8.

Retornar valor

Tipo: HRESULT

Se essa função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

Essa função executa tarefas como substituir caracteres não seguros por suas sequências de escape e sequências de recolhimento, como ".....".

Se uma cadeia de caracteres de URL contiver "/.. /" ou "/./", UrlCanonicalize trata os caracteres como indicando a navegação na hierarquia de URL. A função simplifica as URLs antes de combiná-las. Por exemplo, "/hello/cruel/.. /world" é simplificado para "/hello/world". Exceções a esse comportamento padrão ocorrem nestes casos:

  • Se o sinalizador URL_DONT_SIMPLIFY for definido em dwFlags, a função não simplificará as URLs. Nesse caso, "/hello/cruel/.. /world" é deixado como está.
  • Se "/.. /" ou "/./" é o primeiro segmento no caminho (por exemplo, "http://domain/../path1/path2/file.htm"), UrlCanonicalize gera o caminho exatamente como foi a entrada.

Observação

O cabeçalho shlwapi.h define UrlCanonicalize 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

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional, Windows XP [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 shlwapi.h
Biblioteca Shlwapi.lib
DLL Shlwapi.dll (versão 5.0 ou posterior)

Confira também

Manipulando localizadores de recursos uniformes