Função InternetGetCookieExA (wininet.h)

Artigo
03/04/2024

A função InternetGetCookieEx recupera dados armazenados em cookies associados a uma URL especificada. Ao contrário de InternetGetCookie, InternetGetCookieEx pode ser usado para restringir os dados recuperados a um único nome de cookie ou, por política, associado a sites não confiáveis ou cookies de terceiros.

Sintaxe

BOOL InternetGetCookieExA(
  [in]                LPCSTR  lpszUrl,
  [in]                LPCSTR  lpszCookieName,
  [in, out, optional] LPSTR   lpszCookieData,
  [in, out]           LPDWORD lpdwSize,
  [in]                DWORD   dwFlags,
  [in]                LPVOID  lpReserved
);

Parâmetros

[in] lpszUrl

Um ponteiro para uma cadeia de caracteres terminada em nulo que contém a URL à qual o cookie a ser recuperado está associado. Esse parâmetro não pode ser NULL ou o InternetGetCookieEx falha e retorna um erro ERROR_INVALID_PARAMETER .

[in] lpszCookieName

Um ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome do cookie a ser recuperado. Esse nome diferencia maiúsculas de minúsculas.

[in, out, optional] lpszCookieData

Um ponteiro para um buffer para receber os dados do cookie.

[in, out] lpdwSize

Um ponteiro para uma variável DWORD.

Na entrada, a variável deve conter o tamanho, em TCHARs, do buffer apontado pelo parâmetro pchCookieData .

Na saída, se a função for bem-sucedida, essa variável conterá o número de TCHARs de dados de cookie copiados para o buffer. Se NULL tiver sido passado como o parâmetro lpszCookieData ou se a função falhar com um erro de ERROR_INSUFFICIENT_BUFFER, a variável conterá o tamanho, em BYTEs, do buffer necessário para receber os dados do cookie.

Esse parâmetro não pode ser NULL ou o InternetGetCookieEx falha e retorna um erro ERROR_INVALID_PARAMETER .

[in] dwFlags

Um sinalizador que controla como a função recupera dados de cookie. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
INTERNET_COOKIE_HTTPONLY	Habilita a recuperação de cookies marcados como "HTTPOnly". Não use esse sinalizador se você expor uma interface com script, pois isso tem implicações de segurança. É imperativo que você use esse sinalizador somente se puder garantir que nunca exporá o cookie ao código de terceiros por meio de um mecanismo de extensibilidade fornecido. Versão: Requer a Internet Explorer 8.0 ou posterior.
INTERNET_COOKIE_THIRD_PARTY	Recupera apenas cookies de terceiros se a política permitir explicitamente que todos os cookies para a URL especificada sejam recuperados.
INTERNET_FLAG_RESTRICTED_ZONE	Recupera apenas cookies que seriam permitidos se a URL especificada não fosse confiável; ou seja, se pertencesse à zona URLZONE_UNTRUSTED.

Valor

Significado

INTERNET_COOKIE_HTTPONLY

Habilita a recuperação de cookies marcados como "HTTPOnly".

Não use esse sinalizador se você expor uma interface com script, pois isso tem implicações de segurança. É imperativo que você use esse sinalizador somente se puder garantir que nunca exporá o cookie ao código de terceiros por meio de um mecanismo de extensibilidade fornecido.

Versão: Requer a Internet Explorer 8.0 ou posterior.

INTERNET_COOKIE_THIRD_PARTY

Recupera apenas cookies de terceiros se a política permitir explicitamente que todos os cookies para a URL especificada sejam recuperados.

INTERNET_FLAG_RESTRICTED_ZONE

Recupera apenas cookies que seriam permitidos se a URL especificada não fosse confiável; ou seja, se pertencesse à zona URLZONE_UNTRUSTED.

[in] lpReserved

Reservado para uso futuro. Defina como NULL.

Retornar valor

Se a função for bem-sucedida, a função retornará TRUE.

Se a função falhar, ela retornará FALSE. Para obter um valor de erro específico, chame GetLastError.

Se NULL for passado para lpszCookieData, a chamada terá êxito e a função não definirá ERROR_INSUFFICIENT_BUFFER.

Os códigos de erro a seguir podem ser definidos por essa função.

Código de retorno	Descrição
ERROR_INSUFFICIENT_BUFFER	Retornado se os dados de cookie recuperados forem maiores do que o tamanho do buffer apontado pelo parâmetro pcchCookieData ou se esse parâmetro for NULL.
ERROR_INVALID_PARAMETER	Retornado se o parâmetro pchURL ou pcchCookieData for NULL.
ERROR_NO_MORE_ITEMS	Retornado se nenhum dado com cookie, conforme especificado, puder ser recuperado.

Comentários

Nota O WinINet não dá suporte a implementações de servidor. Além disso, ele não deve ser usado de um serviço. Para implementações de servidor ou serviços, use Os Serviços HTTP do Microsoft Windows (WinHTTP).

Observação

O cabeçalho wininet.h define InternetGetCookieEx 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 XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	wininet.h
Biblioteca	Wininet.lib
DLL	Wininet.dll