Função UrlEscapeW (shlwapi.h)

Artigo
11/20/2024

Converte caracteres ou pares alternativos em uma URL que pode ser alterada durante o transporte pela Internet (caracteres "não seguros") em suas sequências de escape correspondentes. Pares alternativos são caracteres entre U+10000 a U+10FFFF (em UTF-32) ou entre DC00 a DFFF (em UTF-16).

Sintaxe

LWSTDAPI UrlEscapeW(
  [in]      PCWSTR pszUrl,
  [out]     PWSTR  pszEscaped,
  [in, out] DWORD  *pcchEscaped,
            DWORD  dwFlags
);

Parâmetros

[in] pszUrl

Tipo: PCTSTR

Uma cadeia de caracteres terminada em nulo de comprimento máximo INTERNET_MAX_URL_LENGTH que contém uma URL completa ou parcial, conforme apropriado para o valor em dwFlags.

[out] pszEscaped

Tipo: PTSTR

O buffer que recebe a cadeia de caracteres convertida, com os caracteres não seguros convertidos em suas sequências de escape.

[in, out] pcchEscaped

Tipo: DWORD*

Um ponteiro para um valor DWORD que, na entrada, contém o número de caracteres no buffer de pszEscaped . Antes de chamar urlEscape, o aplicativo de chamada deve definir o valor referenciado por pcchEscaped para o tamanho do buffer. Quando essa função retorna com êxito, o valor recebe o número de caracteres gravados no buffer, não incluindo a terminação caractere NULL.

Se um código de erro E_POINTER for retornado, o buffer será muito pequeno para conter o resultado e o valor referenciado por pcchEscaped será definido como o número necessário de caracteres no buffer. Se outros erros forem retornados, o valor referenciado por pcchEscaped será indefinido.

dwFlags

Tipo: DWORD

Os sinalizadores que indicam qual parte da URL está sendo fornecida em pszURL e quais caracteres nessa cadeia de caracteres devem ser convertidos em suas sequências de escape. Os sinalizadores a seguir são definidos.

URL_DONT_ESCAPE_EXTRA_INFO (0x02000000)

Usado somente em conjunto com URL_ESCAPE_SPACES_ONLY para impedir a conversão de caracteres na consulta (a parte da URL após o primeiro caractere # ou ? encontrado na cadeia de caracteres). Esse sinalizador não deve ser usado sozinho, nem combinado com URL_ESCAPE_SEGMENT_ONLY.

URL_BROWSER_MODE

Definido como o mesmo que URL_DONT_ESCAPE_EXTRA_INFO.

URL_ESCAPE_SPACES_ONLY (0x04000000)

Converta apenas caracteres de espaço em suas sequências de escape, incluindo os caracteres de espaço na parte de consulta da URL. Outros caracteres não seguros não são convertidos em suas sequências de escape. Esse sinalizador pressupõe que pszURL não contém uma URL completa. Ele espera apenas as partes que seguem a especificação do servidor.

Combine esse sinalizador com URL_DONT_ESCAPE_EXTRA_INFO para impedir a conversão de caracteres de espaço na parte de consulta da URL.

Esse sinalizador não pode ser combinado com URL_ESCAPE_PERCENT ou URL_ESCAPE_SEGMENT_ONLY.

URL_ESCAPE_PERCENT (0x00001000)

Converta qualquer caractere % encontrado na seção de segmento da URL (aquela seção que está caindo entre a especificação do servidor e o primeiro caractere # ou ? ). Por padrão, o caractere % não é convertido em sua sequência de escape. Outros caracteres não seguros no segmento também são convertidos normalmente.

Combinar esse sinalizador com URL_ESCAPE_SEGMENT_ONLY inclui esses caracteres % na parte de consulta da URL. No entanto, como o sinalizador URL_ESCAPE_SEGMENT_ONLY faz com que toda a cadeia de caracteres seja considerada o segmento, qualquer # ou ? os caracteres também são convertidos.

Esse sinalizador não pode ser combinado com URL_ESCAPE_SPACES_ONLY.

URL_ESCAPE_SEGMENT_ONLY (0x00002000)

Indica que pszURL contém apenas essa seção da URL seguindo o componente do servidor, mas antes da consulta. Todos os caracteres não seguros na cadeia de caracteres são convertidos. Se uma URL completa for fornecida quando esse sinalizador for definido, todos os caracteres não seguros na cadeia de caracteres inteira serão convertidos, incluindo # e ? Caracteres.

Combine esse sinalizador com URL_ESCAPE_PERCENT para incluir esse caractere na conversão.

Esse sinalizador não pode ser combinado com URL_ESCAPE_SPACES_ONLY ou URL_DONT_ESCAPE_EXTRA_INFO.

URL_ESCAPE_AS_UTF8 (0x00040000)

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

URL_ESCAPE_ASCII_URI_COMPONENT (0x00080000)

Windows 8 e posteriores. Codificar por porcentagem todos os caracteres ASCII fora do conjunto não reservado do URI RFC 3986 (a-zA-Z0-9-.~_).

Valor de retorno

Tipo: HRESULT

Retorna S_OK se bem-sucedido. Se o pcchEscaped buffer for muito pequeno para conter o resultado, E_POINTER será retornado e o valor apontado por pcchEscaped será definido como o tamanho do buffer necessário. Caso contrário, um valor de erro padrão será retornado.

Observações

Para fins deste documento, uma URL típica é dividida em três seções: o servidor, o segmento e a consulta. Por exemplo:

http://microsoft.com/test.asp?url=/example/abc.asp?frame=true#fragment

A parte do servidor é "http://microsoft.com/". A barra à direita é considerada parte da parte do servidor.

A parte do segmento é qualquer parte do caminho encontrado seguindo a parte do servidor, mas antes do primeiro # ou ? caractere, nesse caso, simplesmente "test.asp".

A parte da consulta é o restante do caminho do primeiro # ou ? caractere (inclusive) até o final. No exemplo, é "?url=/example/abc.asp?frame=true#fragment".

Caracteres não seguros são os caracteres que podem ser alterados durante o transporte pela Internet. Essa função converte caracteres não seguros em suas sequências de escape equivalentes de "%xy". A tabela a seguir mostra caracteres não seguros e suas sequências de escape.

Personagem	Sequência de escape
^	%5E
&	%26
`	%60
{	%7B
}	%7D
\|	%7C
]	%5D
[	%5B
"	%22
<	%3C
>	%3E
\	%5C

O uso do sinalizador URL_ESCAPE_SEGMENT_ONLY também causa a conversão do # (%23), ? (%3F) e / (%2F) caracteres.

Por padrão, urlEscape ignora qualquer texto após um # ou ? personagem. O sinalizador URL_ESCAPE_SEGMENT_ONLY substitui esse comportamento em relação a toda a cadeia de caracteres como o segmento. O sinalizador URL_ESCAPE_SPACES_ONLY substitui esse comportamento, mas apenas para caracteres de espaço.

Exemplos

Os exemplos a seguir mostram o efeito dos vários sinalizadores em uma URL. A URL de exemplo não é válida, mas é exagerada para fins de demonstração.


// The full original URL
http://microsoft.com/test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment    

// URL_ESCAPE_SPACES_ONLY 
// Only space characters are escaped. Other unsafe characters are ignored.
// Note: This flag expects the server portion of the URL to be omitted.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result   = test/t%e<s%20t.asp?url=/{ex%%20ample</abc.asp?frame=true#fr%agment

// URL_ESCAPE_SPACES_ONLY | URL_DONT_ESCAPE_EXTRA_INFO
// Spaces in the segment are converted into their escape sequences, but
// spaces in the query are not.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result   = test/t%e<s%20t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment

// URL_ESCAPE_PERCENT
// Here only the segment and query are supplied and the server component is
// omitted, although that is not required. Only the segment is considered.
// All unsafe characters plus the % character are converted in the segment.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result   = test/t%25e%3Cs%20t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment

// URL_ESCAPE_SEGMENT_ONLY
// Note: This flag expects only the segment, omitting the server and query 
//       components.
// The / character is escaped as well as the usual unsafe characters.
Original = test/t%e<s t.asp
Result   = test%2Ft%e%3Cs%20t.asp

Nota

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