Função UrlCombineW (shlwapi.h)

  • Artigo

Quando fornecido com uma URL relativa e sua base, retorna uma URL em forma canônica.

Sintaxe

LWSTDAPI UrlCombineW(
  [in]            PCWSTR pszBase,
  [in]            PCWSTR pszRelative,
  [out, optional] PWSTR  pszCombined,
  [in, out]       DWORD  *pcchCombined,
                  DWORD  dwFlags
);

Parâmetros

[in] pszBase

Tipo: PCTSTR

Um ponteiro para uma cadeia de caracteres terminada em nulo de comprimento máximo INTERNET_MAX_URL_LENGTH que contém a URL base.

[in] pszRelative

Tipo: PCTSTR

Um ponteiro para uma cadeia de caracteres terminada em nulo de comprimento máximo INTERNET_MAX_URL_LENGTH que contém a URL relativa.

[out, optional] pszCombined

Tipo: PTSTR

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

[in, out] pcchCombined

Tipo: DWORD*

Um ponteiro para um valor que, na entrada, é definido como o número de caracteres no buffer pszCombined . Quando a função retorna com êxito, o valor depende se a função é bem-sucedida ou retorna E_POINTER. Para outros valores retornados, o valor desse parâmetro não tem sentido.

dwFlags

Tipo: DWORD

Sinalizadores que especificam como a URL é convertida em formulário canônico. Os sinalizadores a seguir podem ser combinados.

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 obter mais discussões.

URL_ESCAPE_PERCENT (0x00001000)

Converta qualquer ocorrência de '%' em sua sequência de escape.

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_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_NO_META

Definido como o mesmo que URL_DONT_SIMPLIFY.

URL_PLUGGABLE_PROTOCOL (0x40000000)

Combine URLs com protocolos conectáveis definidos pelo cliente, de acordo com a especificação 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_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 ignoradas. 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_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

Retorna códigos de erro COM padrão, incluindo o seguinte.

Código de retorno Descrição
S_OK
 pszCombined aponta para uma cadeia de caracteres que contém as URLs combinadas. O valor de pcchCombined é definido como o número de caracteres na cadeia de caracteres, sem contar o caractere NULL de terminação.
E_POINTER
 O buffer era muito pequeno. O valor de pcchCombined é definido como o número mínimo de caracteres que o buffer deve ser capaz de conter, incluindo o caractere NULL de terminação.

Comentários

Os itens entre barras são tratados como identificadores hierárquicos; o último item especifica o documento em si. Você deve inserir uma barra (/) após o nome do documento para acrescentar mais itens; caso contrário, UrlCombine troca um documento por outro. Por exemplo:


hRetVal = UrlCombine(TEXT("http://xyz/test/abc"), 
                     TEXT("bar"), 
                     lpszCombined, 
                     &dwLength, 0);

O código anterior retorna a URL http://xyz/test/bar. Se você quiser que a URL combinada seja http://xyz/test/abc/bar, use a chamada a seguir para UrlCombine.


hRetVal = UrlCombine(TEXT("http://xyz/test/abc/"), 
                     TEXT("bar"), 
                     lpszCombined, 
                     &dwLength, 0);

Se uma cadeia de caracteres de URL contiver '/.. /' ou '/./', UrlCombine geralmente trata os caracteres como se indicassem 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". 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á.

Observação

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

UrlCanonicalize