Obsługa plików cookie w usłudze WinHTTP

Dane sesji HTTP są przekazywane między klientem a serwerem w nagłówku pliku cookie żądania lub odpowiedzi. Serwer wysyła pliki cookie do klienta w nagłówku Set-cookie odpowiedzi, a interfejs API WinHTTP ponownie wysyła plik cookie serwera do serwera w nagłówku pliku cookie żądania. Specyfikacje obsługi plików cookie opisane w rfc 2109 (mechanizm zarządzania stanem HTTP) są domyślnie implementowane w winHTTP. Najnowsze specyfikacje obsługi plików cookie opisane w rfc 2964 nie są obsługiwane przez WinHTTP.

WinHTTP uzyskuje plik cookie z nagłówka serwera Set-Cookie i zapisuje go w pamięci podręcznej osobno dla każdej sesji. Ten plik cookie jest ponownie wysyłany do kolejnych żądań w tej samej sesji WinHTTP, gdzie obiekt docelowy odpowiada źródle pliku cookie. Interfejs API WinHTTP ponownie generuje nagłówek ciasteczka żądania dla każdego etapu w żądaniu.

Na poniższej liście opisano kilka opcji, których aplikacje klienckie WinHTTP mogą używać do obsługi plików cookie:

• Automatyczna obsługa plików cookie — winHTTP automatycznie obsługuje pliki cookie, a aplikacja kliencka nie wykonuje niestandardowej obsługi plików cookie.
• Wyłącz automatyczną obsługę plików cookie — automatyczna obsługa plików cookie w interfejsie API WinHTTP jest wyłączona i nie są wysyłane żadne pliki cookie.
• Ręcznie określ wszystkie pliki cookie — automatyczna obsługa plików cookie jest wyłączona, a aplikacja kliencka dodaje lub usuwa wszystkie nagłówki plików cookie dla każdego żądania w sesji.
• Ręczna i automatyczna obsługa plików cookie — łączenie automatycznej i ręcznej obsługi plików cookie.

Wyłączanie automatycznej obsługi plików cookie

Aby wyłączyć obsługę plików cookie, aplikacja kliencka WinHTTP wywołuje funkcję WinHttpSetOption z parametrem dwOption ustawionym na WINHTTP_OPTION_DISABLE_FEATURE, a parametr lpBuffer ustawiony na WINHTTP_DISABLE_COOKIES. Parametr hInternet musi być uchwytem żądania. Gdy obsługa plików cookie jest wyłączona na dojściu żądań, który wysłał poprzednie żądanie, klient powinien ręcznie usunąć istniejące nagłówki plików cookie żądania za pomocą funkcji WinHttpAddRequestHeaders przed wysłaniem następnego żądania. Aby uzyskać więcej informacji, zobacz Usuwanie nagłówków plików cookie.

Ręczne określanie wszystkich plików cookie

Gdy automatyczna obsługa plików cookie jest wyłączona, aplikacja kliencka WinHTTP ma możliwość ręcznego określenia wszystkich plików cookie. Aby ręcznie ustawić plik cookie, aplikacja wywołuje WinHttpAddRequestHeaders określając nagłówek pliku cookie w parametrze pwszHeaders. Aplikacja kliencka powinna wyczyścić wszystkie nagłówki plików cookie przed ponownym wysłaniem żądania.

Aplikacja kliencka powinna również zmienić nagłówek pliku cookie po przekierowaniu żądania. Aby zmienić plik cookie na przekierowanych żądaniach, klient określa funkcję wywołania zwrotnego z WinHttpSetStatusCallback, która odpowiada na przypadek wywołania zwrotnego przekierowania. Procedura obsługi wywołania zwrotnego powinna wyczyścić plik cookie wcześniej wysłany na żądanie, wywołując WinHttpAddRequestHeaders. Aby uzyskać więcej informacji na temat usuwania nagłówków plików cookie, zobacz Usuwanie nagłówków plików cookie.

Ręczna i automatyczna obsługa plików cookie

Aplikacje klienckie WinHTTP mogą łączyć mechanizm automatycznej obsługi plików cookie WinHTTP z ręczną obsługą plików cookie. Aplikacja dodaje niestandardowe pliki cookie do automatycznie wygenerowanego nagłówka pliku cookie przed wysłaniem żądania za pomocą funkcji WinHttpSendRequest. Niestandardowy plik cookie powinien być pierwszym nagłówkem pliku cookie w żądaniu interfejsu API WinHTTP, aby prawidłowo buforować plik cookie. Aplikacja kliencka powinna również usuwać pliki cookie wysyłane w poprzednich żądaniach przed ponownym wysłaniem żądania na tym samym uchwycie żądania. Aby uzyskać więcej informacji, zobacz Usuwanie nagłówków plików cookie.

Pliki cookie dodane do żądania przed wywołaniem WinHttpSendRequest są uwzględniane we wszystkich żądaniach WinHTTP wysłanych dla następnego WinHttpSendRequest i WinHttpReceiveResponse. Aplikacja kliencka może wymagać wyczyszczenia nagłówka pliku cookie po przekierowaniu żądania. Aby wyczyścić plik cookie w przypadku przekierowanych żądań, klient określa funkcję zwrotną przy użyciu WinHttpSetStatusCallback, która reaguje na zdarzenie przekierowania. Procedura obsługi wywołania zwrotnego powinna wyczyścić plik cookie, który został wcześniej wysłany na żądanie, wywołując WinHttpAddRequestHeaders. Funkcja wywołania zwrotnego może nie ustawiać nowych niestandardowych plików cookie na wywołaniu zwrotnym przekierowania. Klient musi poczekać na ukończenie WinHttpReceiveResponse przed dodaniem nowych plików cookie do następnego wywołania WinHttpSendRequest .

Usuwanie nagłówków plików cookie

Aplikacja kliencka WinHTTP może wymagać wyczyszczenia istniejącego pliku cookie zapytania przed ponownym wysłaniem zapytania, aby zapobiec wysyłaniu plików cookie, które zostały wysłane w poprzednich zapytaniach, ponownie w bieżącym zapytaniu; aby uzyskać więcej informacji, zobacz następującą notatkę. Należy również pamiętać, że pliki cookie nie muszą być usuwane przed wysłaniem pierwszego żądania na uchwyt żądania. Klient może wyczyścić istniejące pliki cookie, wywołując WinHttpAddRequestHeaders z pustym nagłówkiem pliku cookie w parametrze pwszHeaders i flagą WINHTTP_ADDREQ_FLAG_REPLACE ustawioną w parametrze dwModifier. Poniższy przykład kodu pokazuje, jak wyczyścić nagłówek pliku cookie w żądaniu.

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

Interfejs API WinHTTP ma różne zachowania obsługi plików cookie dla wersji systemu operacyjnego starszych niż Windows XP z dodatkiem Service Pack 2 (SP2) i Windows Server 2003 z dodatkiem Service Pack 1 (SP1).

**Windows XP z dodatkiem SP2 lub nowszym oraz windows Server 2003 z dodatkiem SP1 lub nowszym: **

Interfejs API WinHTTP czyści wszystkie pliki cookie wysyłane w poprzednich żądaniach do obsługi żądań. Klient może ręcznie dodać nowe nagłówki plików cookie przed każdym wywołaniem metody WinHttpSendRequest. Jeśli funkcja automatycznego obsługi plików cookie interfejsu API WinHTTP nie została wyłączona, interfejs API WinHTTP dołączy nowy nagłówek pliku cookie (lub doda nowy nagłówek pliku cookie, jeśli aplikacja kliencka nie dodała go ręcznie) z plikiem cookie z serwera.

**Windows XP z dodatkiem SP2 i Windows Server 2003 z dodatkiem SP1: **

Interfejs API WinHTTP nie czyści nagłówka cookie żądania po zakończeniu WinHttpReceiveResponse. Pliki cookie wysyłane w poprzednich żądaniach będą ponownie wysyłane w kolejnych wywołaniach usługi WinHttpSendRequest. Aplikacja kliencka WinHTTP powinna wyczyścić istniejące nagłówki cookie przed ponownym wysłaniem żądania na uchwycie żądania.