Compartilhar via

Manipulação de cookies em WinHTTP

  • Artigo

Os dados da sessão HTTP são passados entre o cliente e o servidor no cabeçalho de 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 de servidor para o servidor no cabeçalho de cookie da solicitação. As especificações de manipulação de cookie, descritas no rfc 2109 (Mecanismo de Gerenciamento de Estado HTTP), são implementadas por padrão no WinHTTP. As especificações recentes de manipulação de cookie, descritas no rfc 2964, não têm suporte do WinHTTP.

O WinHTTP obtém o cookie dos servidores Set-Cookie cabeçalho e o armazena em um cache por sessão. Esse cookie é ressentido em solicitações subsequentes na mesma sessão WinHTTP em que o destino corresponde à origem do cookie. A API WinHTTP regenera o cabeçalho de cookie de solicitação para cada etapa na solicitação.

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

  • Manipulação automática de cookie – o WinHTTP manipula automaticamente cookies e o aplicativo cliente não executa nenhuma manipulação de cookie personalizada.
  • Desabilitar Manipulação Automática de Cookie – o tratamento automático de cookie na API WinHTTP está desabilitado e nenhum cookies é enviado.
  • Especifique manualmente todos os Cookies – a manipulação automática de cookie está desabilitada e o aplicativo cliente adiciona ou remove todos os cabeçalhos de cookie para cada solicitação na sessão.
  • Manipulação manual e automática de cookie – combine a manipulação automática e manual de cookie.

Para desabilitar a manipulação de cookie, o aplicativo cliente WinHTTP chama a função WinHttpSetOption com o parâmetro dwOption definido como WINHTTP_OPTION_DISABLE_FEATURE e o parâmetro lpBuffer definido como WINHTTP_DISABLE_COOKIES. O parâmetro hInternet deve ser um identificador de solicitação. Quando a manipulação de cookie é desabilitada 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ção WinHttpAddRequestHeaders antes de enviar a próxima solicitação. Para obter mais informações, consulte Removendo cabeçalhos de cookie.

Observação

O aplicativo cliente deve definir todos os cookies na sessão depois que o modo automático tiver sido desabilitado.

Especificando manualmente todos os cookies

Quando a manipulação automática de cookie é desabilitada, o aplicativo cliente WinHTTP tem a opção de especificar manualmente todos os cookies. Para definir manualmente o cookie, o aplicativo chama WinHttpAddRequestHeaders especificando o cabeçalho de 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 tiver sido 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 cookie, consulte Removendo cabeçalhos de cookie.

Os aplicativos cliente WinHTTP podem combinar o mecanismo de manipulação automática de cookie winHTTP com manipulação manual de cookie. O aplicativo adiciona cookies personalizados ao cabeçalho de cookie 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 o cookie em cache. O aplicativo cliente também deve remover 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 cookie.

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 das próximas chamadas WinHttpSendRequest e WinHttpReceiveResponse . Talvez o aplicativo cliente precise limpar o cabeçalho do cookie quando a solicitação tiver sido 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 de chamada pode não definir novos cookies personalizados no retorno de chamada de redirecionamento. O cliente deve aguardar a conclusão do 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 cookies enviados em solicitações anteriores sejam enviados novamente na solicitação atual; para obter mais informações, consulte a seguinte Observação. Lembre-se também de que os Cookies não precisam ser limpos antes que a primeira solicitação seja enviada no identificador de solicitação. O cliente pode limpar 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 de cookie na solicitação.

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

A API WinHTTP tem comportamentos diferentes de manipulação de cookie 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 cookie da API WinHTTP não tiver sido desabilitada, a API WinHTTP acrescentará o novo cabeçalho de cookie (ou adicionará um novo cabeçalho de cookie se o aplicativo cliente não tiver adicionado 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 de cookie de solicitação após a conclusão de WinHttpReceiveResponse . Os cookies enviados em solicitações anteriores serão ressentidos em chamadas subsequentes para WinHttpSendRequest. O aplicativo cliente WinHTTP deve limpar cabeçalhos de cookies existentes antes de reenviar uma solicitação no identificador de solicitação.