Partilhar via

Tratamento de cookies no WinHTTP

  • Artigo

Os dados da sessão HTTP são passados entre o cliente e o servidor no cabeçalho do cookie da solicitação ou da resposta. O servidor envia cookies para o cliente no cabeçalho Set-cookie da resposta e a API WinHTTP reenvia o cookie do servidor para o servidor no cabeçalho do cookie da solicitação. As especificações de manipulação de cookies, descritas em rfc 2109 (HTTP State Management Mechanism), são implementadas por padrão no WinHTTP. As especificações recentes de tratamento de cookies, descritas no rfc 2964, não são suportadas pelo WinHTTP.

WinHTTP obtém o cookie dos cabeçalhos Set-Cookie dos servidores e armazena-o numa cache por sessão. Este cookie é reenviado em pedidos subsequentes na mesma sessão WinHTTP em que o destino corresponde à origem do cookie. A API do WinHTTP regenera o cabeçalho do cookie de solicitação para cada etapa da solicitação.

A lista a seguir descreve várias opções que os aplicativos cliente WinHTTP podem usar para lidar com cookies:

  • Tratamento automático de cookies - O WinHTTP lida automaticamente com cookies e o aplicativo cliente não executa nenhum tratamento personalizado de cookies.
  • Desativar o tratamento automático de cookies - O tratamento automático de cookies na API WinHTTP está desativado e nenhum cookie é enviado.
  • Especificar manualmente todos os Cookies – O tratamento automático de cookies está desativado e a aplicação cliente adiciona ou remove todos os cabeçalhos de cookies para cada pedido na sessão.
  • Tratamento manual e automático de cookies - Combine o tratamento automático e manual de cookies.

Para desativar o tratamento de cookies, o aplicativo cliente WinHTTP chama a funçãoWinHttpSetOptioncom o parâmetro dwOption definido como WINHTTP_OPTION_DISABLE_FEATUREe o parâmetro lpBuffer definido como WINHTTP_DISABLE_COOKIES. O parâmetro hInternet deve ser um identificador de solicitação. Quando o tratamento de cookies é desativado em um identificador de solicitação que enviou uma solicitação anterior, o cliente deve remover manualmente os cabeçalhos de cookie de solicitação existentes com a funçãoWinHttpAddRequestHeadersantes de enviar a próxima solicitação. Para obter mais informações, consulte Removendo cabeçalhos de cookies.

Observação

O aplicativo cliente deve definir todos os cookies na sessão após o modo automático ter sido desativado.

Especificar manualmente todos os cookies

Quando o tratamento automático de cookies está desativado, o aplicativo cliente WinHTTP tem a opção de especificar manualmente todos os cookies. Para definir manualmente o cookie, a aplicação chama WinHttpAddRequestHeaders especificando o cabeçalho do cookie no parâmetro pwszHeaders. O aplicativo cliente deve limpar todos os cabeçalhos de cookie antes de reenviar a solicitação.

O aplicativo cliente também deve alterar o cabeçalho do cookie quando a solicitação for redirecionada. Para alterar o cookie em solicitações redirecionadas, o cliente especifica uma função de retorno de chamada com WinHttpSetStatusCallback que responde ao caso de retorno de chamada de redirecionamento. O manipulador de retorno de chamada deve limpar o cookie enviado anteriormente na solicitação chamando WinHttpAddRequestHeaders. Para obter mais informações sobre como remover cabeçalhos de cookies, consulte Removendo cabeçalhos de cookies.

Os aplicativos cliente WinHTTP podem combinar o mecanismo automático de manipulação de cookies WinHTTP com o tratamento manual de cookies. A aplicação adiciona cookies personalizados ao cabeçalho de cookies gerado automaticamente antes de enviar a solicitação com a função WinHttpSendRequest. O cookie personalizado deve ser o primeiro cabeçalho de cookie na solicitação para que a API WinHTTP armazene corretamente em cache o cookie. O aplicativo cliente também deve remover os cookies enviados em solicitações anteriores antes de reenviar uma solicitação no mesmo identificador de solicitação. Para obter mais informações, consulte Removendo cabeçalhos de cookies.

Os cookies adicionados a uma solicitação antes da chamada para WinHttpSendRequest são incluídos em todas as solicitações WinHTTP enviadas em nome da seguinte chamada WinHttpSendRequest e das chamadas WinHttpReceiveResponse. O aplicativo cliente pode precisar limpar o cabeçalho do cookie quando a solicitação for redirecionada. Para limpar o cookie em solicitações redirecionadas, o cliente especifica uma função de retorno de chamada com WinHttpSetStatusCallback que responde ao caso de retorno de chamada de redirecionamento. O manipulador de retorno de chamada deve limpar o cookie que foi enviado anteriormente na solicitação chamando WinHttpAddRequestHeaders. A função de retorno pode não definir novos cookies personalizados durante o redirecionamento. O cliente deve aguardar a conclusão de WinHttpReceiveResponse antes de adicionar novos cookies para a próxima chamada WinHttpSendRequest.

O aplicativo cliente WinHTTP pode precisar limpar o cookie de solicitação existente antes de reenviar uma solicitação para impedir que os cookies que foram enviados em solicitações anteriores sejam enviados novamente na solicitação atual; para obter mais informações, consulte a seguinte Nota. Tenha também em atenção que os Cookies não precisam ser eliminados antes do envio do primeiro pedido no gestor de pedidos. O cliente pode limpar os cookies existentes chamando WinHttpAddRequestHeaders com um cabeçalho de cookie vazio no parâmetro pwszHeaders e o sinalizador WINHTTP_ADDREQ_FLAG_REPLACE definido no parâmetro dwModifier. O exemplo de código a seguir mostra como limpar o cabeçalho do cookie na solicitação.

WinHttpAddRequestHeaders(hRequest, 
                         L"Cookie:", 
                         -1, 
                         WINHTTP_ADDREQ_FLAG_REPLACE);

A API WinHTTP tem diferentes comportamentos de manipulação de cookies para versões do sistema operacional anteriores ao Windows XP com Service Pack 2 (SP2) e Windows Server 2003 com Service Pack 1 (SP1).

**Windows XP com SP2 e posterior e Windows Server 2003 com SP1 e posterior: **

A API WinHTTP limpa todos os cookies enviados em solicitações anteriores para o identificador de solicitação. O cliente pode adicionar manualmente novos cabeçalhos de cookie antes de cada chamada para WinHttpSendRequest. Se a funcionalidade de manipulação automática de cookies da API WinHTTP não tiver sido desativada, a API WinHTTP acrescentará o novo cabeçalho de cookie (ou adicionará um novo cabeçalho de cookie se o aplicativo cliente não adicionou um manualmente) com o cookie do servidor.

**Windows XP com SP2 e Windows Server 2003 com SP1: **

A API WinHTTP não limpa o cabeçalho do cookie de solicitação após WinHttpReceiveResponse ter concluído. Os cookies enviados em pedidos anteriores serão reenviados em chamadas subsequentes para WinHttpSendRequest. O aplicativo cliente WinHTTP deve limpar os cabeçalhos de cookies existentes antes de reenviar uma solicitação no identificador de solicitação.