Função UrlCombineA (shlwapi.h)

Artigo
11/20/2024

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

Sintaxe

LWSTDAPI UrlCombineA(
  [in]            PCSTR pszBase,
  [in]            PCSTR pszRelative,
  [out, optional] PSTR  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 de 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 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 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_NO_META

Definido como o mesmo que URL_DONT_SIMPLIFY.

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

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 a terminação caractere NULL.
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 a terminação caractere de NULL.

Observações

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 de URL_DONT_SIMPLIFY estiver definido em dwFlags, a função não simplificará as URLs. Nesse caso, "/hello/cruel/.. /world" é deixado como está.

Nota

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

urlCanonicalize

Compartilhar via