Partilhar via

Funções de utilitário de HTTP da ATL

  • Artigo

Essas funções dão suporte à manipulação de URLs.

Função Descrição
AtlCanonicalizeUrl Canonicaliza uma URL, que inclui a conversão de caracteres e espaços desprotegidos em sequências de escape.
AtlCombineUrl Combina uma URL de base e uma URL relativa em uma única URL canônica.
AtlEscapeUrl Converte todos os caracteres desprotegidos em sequências de escape.
AtlGetDefaultUrlPort Obtém o número da porta padrão associada a um IP ou esquema específico.
AtlIsUnsafeUrlChar Determina se um caractere é seguro para uso em uma URL.
AtlUnescapeUrl Converte caracteres de escape de volta aos valores originais.
RGBToHtml Converte um valor COLORREF no texto HTML correspondente ao valor da cor.
SystemTimeToHttpDate Chame essa função para converter uma hora do sistema em uma cadeia de caracteres em um formato adequado para uso em cabeçalhos HTTP.

Requisitos

Cabeçalho: atlutil.h

AtlCanonicalizeUrl

Chame essa função para canonizar uma URL, o que inclui converter caracteres e espaços não seguros em sequências de escape.

inline BOOL AtlCanonicalizeUrl(
   LPCTSTR szUrl,
   LPTSTR szCanonicalized,
   DWORD* pdwMaxLength,
   DWORD dwFlags = 0) throw();

Parâmetros

szUrl
A URL a ser canonizada.

szCanonicalized
Buffer alocado pelo chamador para receber a URL canônica.

pdwMaxLength
O ponteiro para uma variável que contém o comprimento em caracteres de szCanonicalized. Se a função for bem-sucedida, a variável receberá o número de caracteres gravados no buffer, incluindo o caractere nulo final. Se a função falhar, a variável receberá o comprimento necessário em bytes do buffer, incluindo espaço para o caractere nulo final.

dwFlags
Os sinalizadores ATL_URL que controlam o comportamento dessa função.

  • ATL_URL_BROWSER_MODE não codifica ou decodifica caracteres após "#" ou "?" e não remove o espaço em branco à direita após "?". Se esse valor não for especificado, toda a URL será codificada e o espaço em branco à direita será removido.

  • ATL_URL_DECODE converte todas as sequências %XX em caracteres, incluindo sequências de escape, antes que a URL seja analisada.

  • ATL_URL_ENCODE_PERCENT codifica qualquer sinal de porcentagem encontrado. Por padrão, os sinais de porcentagem não são codificados.

  • ATL_URL_ENCODE_SPACES_ONLY codifica apenas espaços.

  • ATL_URL_ESCAPE converte todas as sequências de escape (%XX) nos caracteres correspondentes.

  • ATL_URL_NO_ENCODE não converte caracteres não seguros em sequências de escape.

  • ATL_URL_NO_META não remove sequências meta (como "." e "..") da URL.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Comporta-se como a versão atual do InternetCanonicalizeUrl, mas não exige que o WinInet ou o Internet Explorer sejam instalados.

AtlCombineUrl

Chame essa função para combinar uma URL de base e uma URL relativa em uma única URL canônica.

inline BOOL AtlCombineUrl(
   LPCTSTR szBaseUrl,
   LPCTSTR szRelativeUrl,
   LPTSTR szBuffer,
   DWORD* pdwMaxLength,
   DWORD dwFlags = 0) throw();

Parâmetros

szBaseUrl
A URL base.

szRelativeUrl
A URL relativa à URL base.

szBuffer
Buffer alocado pelo chamador para receber a URL canônica.

pdwMaxLength
O ponteiro para uma variável que contém o comprimento em caracteres de szBuffer. Se a função for bem-sucedida, a variável receberá o número de caracteres gravados no buffer, incluindo o caractere nulo final. Se a função falhar, a variável receberá o comprimento necessário em bytes do buffer, incluindo espaço para o caractere nulo final.

dwFlags
Os sinalizadores que controlam o comportamento dessa função. Confira AtlCanonicalizeUrl.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Comporta-se como a versão atual do InternetCombineUrl, mas não exige que o WinInet ou o Internet Explorer sejam instalados.

AtlEscapeUrl

Chame essa função para converter todos os caracteres não seguros em sequências de escape.

inline BOOL AtlEscapeUrl(
   LPCSTR szStringIn,
   LPSTR szStringOut,
   DWORD* pdwStrLen,
   DWORD dwMaxLength,
   DWORD dwFlags = 0) throw();

inline BOOL AtlEscapeUrl(
   LPCWSTR szStringIn,
   LPWSTR szStringOut,
   DWORD* pdwStrLen,
   DWORD dwMaxLength,
   DWORD dwFlags = 0) throw();

Parâmetros

lpszStringIn
A URL a ser convertida.

lpszStringOut
Buffer alocado pelo chamador no qual a URL convertida será gravada.

pdwStrLen
Ponteiro para uma variável DWORD. Se a função for bem-sucedida, pdwStrLen receberá o número de caracteres gravados no buffer, incluindo o caractere nulo final. Se a função falhar, a variável receberá o comprimento necessário em bytes do buffer, incluindo espaço para o caractere nulo final. Ao usar a versão de caractere largo desse método, pdwStrLen recebe o número de caracteres necessários, não o número de bytes.

dwMaxLength
O tamanho do buffer lpszStringOut.

dwFlags
Os sinalizadores ATL_URL que controlam o comportamento dessa função. Veja os valores possíveis em ATLCanonicalizeUrl.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

AtlGetDefaultUrlPort

Chame essa função para obter o número da porta padrão associado a um IP ou esquema específico.

inline ATL_URL_PORT AtlGetDefaultUrlPort(ATL_URL_SCHEME m_nScheme) throw();

Parâmetros

m_nScheme
O valor ATL_URL_SCHEME que identifica o esquema para o qual você deseja obter o número da porta.

Valor de retorno

O ATL_URL_PORT associado ao esquema especificado ou ATL_URL_INVALID_PORT_NUMBER se o esquema não for reconhecido.

AtlIsUnsafeUrlChar

Chame essa função para descobrir se um caractere é seguro para uso em uma URL.

inline BOOL AtlIsUnsafeUrlChar(char chIn) throw();

Parâmetros

chIn
O caractere cuja segurança será testada.

Valor de retorno

Retorna TRUE se o caractere de entrada não for seguro. Caso contrário, FALSE.

Comentários

Os caracteres que não devem ser usados em URLs podem ser testados usando essa função e convertidos usando AtlCanonicalizeUrl.

AtlUnescapeUrl

Chame essa função para converter caracteres de escape de volta aos valores originais.

inline BOOL AtlUnescapeUrl(
   LPCSTR szStringIn,
   LPSTR szStringOut,
   LPDWORD pdwStrLen,
   DWORD dwMaxLength) throw();

inline BOOL AtlUnescapeUrl(
   LPCWSTR szStringIn,
   LPWSTR szStringOut,
   LPDWORD pdwStrLen,
   DWORD dwMaxLength) throw();

Parâmetros

lpszStringIn
A URL a ser convertida.

lpszStringOut
Buffer alocado pelo chamador no qual a URL convertida será gravada.

pdwStrLen
Ponteiro para uma variável DWORD. Se a função for bem-sucedida, a variável receberá o número de caracteres gravados no buffer, incluindo o caractere nulo final. Se a função falhar, a variável receberá o comprimento necessário em bytes do buffer, incluindo espaço para o caractere nulo final.

dwMaxLength
O tamanho do buffer lpszStringOut.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Inverte o processo de conversão aplicado por AtlEscapeUrl.

RGBToHtml

Converte um valor COLORREF no texto HTML correspondente ao valor da cor.

bool inline RGBToHtml(
   COLORREF color,
   LPTSTR pbOut,
   long nBuffer);

Parâmetros

color
Um valor para a cor RGB.

pbOut
Buffer alocado pelo chamador para receber o texto do valor de cor HTML. O buffer deve ter espaço para pelo menos 8 caracteres, incluindo espaço para o terminador nulo).

nBuffer
O tamanho em bytes do buffer (incluindo espaço para o terminador nulo).

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Um valor de cor HTML é um sinal de libra seguido por um valor hexadecimal de seis dígitos usando dois dígitos para cada um dos componentes vermelho, verde e azul da cor (por exemplo, #FFFFFF é branco).

SystemTimeToHttpDate

Chame essa função para converter uma hora do sistema em uma cadeia de caracteres em um formato adequado para uso em cabeçalhos HTTP.

inline void SystemTimeToHttpDate(
   const SYSTEMTIME& st,
   CStringA& strTime);

Parâmetros

St
O tempo do sistema a ser obtido como uma cadeia de caracteres de formato HTTP.

strTime
Uma referência a uma variável de cadeia de caracteres para receber a data e hora HTTP conforme definido na RFC 2616 (https://www.ietf.org/rfc/rfc2616.txt) e RFC 1123 (https://www.ietf.org/rfc/rfc1123.txt).

Confira também

Conceitos
Componentes de área de trabalho COM da ATL
InternetCanonicalizeUrl