Função UrlCanonicalizeA (shlwapi.h)

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

Sintaxe

LWSTDAPI UrlCanonicalizeA(
  [in]      PCSTR pszUrl,
  [out]     PSTR  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.

Valor retornado

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 recolhimento de sequências 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.

Requisitos

Confira também

Manipulando localizadores de recursos uniformes