Função UrlCanonicalizeW (shlwapi.h)

Artigo
11/20/2024

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 se referir 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 de 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 são não escapadas. 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 não seguros por 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 pluggable 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 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 qualquer ocorrência de "%" em sua sequência de escape.

URL_ESCAPE_AS_UTF8 (0x00040000)

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

Valor de retorno

Tipo: HRESULT

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

Observações

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". As exceções a esse comportamento padrão ocorrem nesses casos:

Se o sinalizador de URL_DONT_SIMPLIFY estiver 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.

Nota

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 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, Windows XP [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	shlwapi.h
biblioteca	Shlwapi.lib
de DLL	Shlwapi.dll (versão 5.0 ou posterior)

Consulte também

tratando de recursos uniformes

Compartilhar via