WinHTTP如何处理Cookie

WinHTTP如何处理Cookie

HTTP session data is passed between the client and server in the cookie header of the request or the response. The server sends cookies to the client in the Set-cookie header of the response and the WinHTTP API resends the server cookie to the server in the cookie header of the request. The cookie handling specifications, described in rfc 2109 (HTTP State Management Mechanism), are implemented by default in WinHTTP. Recent cookie handling specifications, described in rfc 2964, are not supported by WinHTTP.

客户端和服务器之间的HTTP会话数据都带有Cookie数据。服务器通过Set-cookie头发送Cookie给客户端，WinHTTP客户端再把这些Cookie反发给服务器。WinHTTP实现了RFC2109(HTTP 状态管理机制)。而近期才有的rfc 2964 Cookie管理机制没有在WinHTTP中实现。

WinHTTP obtains the cookie from the servers Set-Cookie header and stores it in a cache on a per-session basis. This cookie is resent on subsequent requests in the same WinHTTP session where the target matches the source of the cookie. The WinHTTP API regenerates the request cookie header for each leg in the request.

WinHTTP从服务器发送的Set-Cookie头中获取Cookie并把它缓存起来是会话的基础。这个Cookie会在后续的请求中重新发送，会话也就是根据源地址和Cookie来界定的。WinHTTP API回味每次请求生成cookie头部。

The follow list describes several options that WinHTTP client applications can use to handle cookies:

下面是WinHTTP客户程序可以做的几种Cookie处理方法。

• Automatic Cookie Handling - WinHTTP automatically handles cookies and the client application performs no custom cookie handling.
• 自动处理 - WinHTTP自动处理Cookie，对cookie客户程序什么也不做。
  
• Disable Automatic Cookie Handling - Automatic cookie handling in the WinHTTP API is disabled and no cookies are sent.
• 关闭自动处理 - 关闭自动cookie处理后发送时就没有cookie啦。
  
• Manually specify all Cookies – Automatic cookie handling is disabled and the client application adds or removes all cookie headers for each request in the session.
• 手动设定 - 自动cookie处理关闭后，客户程序可以针对每个会话添加或删除各种cookie头部。
  
• Manual and Automatic Cookie Handling - Combine automatic and manual cookie handling.
• 手动设定和自动处理相结合 - 结合自动和手动处理
  

Disabling Automatic Cookie Handling

关闭自动处理

To disable cookie handling, the WinHTTP client application calls the WinHttpSetOption function with the dwOption parameter set to WINHTTP_OPTION_DISABLE_FEATURE, and thelpBuffer parameter set to WINHTTP_DISABLE_COOKIES. ThehInternet parameter can be either a session handle or a request handle. When cookie handling is disabled on a request handle that has sent a previous request, the client should manually remove existing request cookie headers with theWinHttpAddRequestHeaders function before sending the next request. For more information, seeRemoving Cookie Headers.

要关闭自动处理，WinHTTP客户程序需要调用WinHttpSetOption函数，把dwOption 参数设为WINHTTP_OPTION_DISABLE_FEATURE, thelpBuffer 参数设置为WINHTTP_DISABLE_COOKIES。hInternet参数可以是会话句柄也可以是请求句柄。

Note  The client application must set all cookies on the session after automatic mode has been disabled.

注意 如果自动模式被禁用，客户程序就必须在会话的后续过程中设置所有所需的cookie.

Manually Specifying All Cookies

手动设定

When automatic cookie handling is disabled, the WinHTTP client application has the option to manually specify all cookies. To manually set the cookie, the application callsWinHttpAddRequestHeaders specifying the cookie header in thepwszHeaders parameter. The client application should clear all cookie headers before resending the request.

当自动处理禁用后，WinHTTP客户程序有手动设置所有cookie的选择权。要手动设置cookie，程序要调用WinHttpAddRequestHeaders函数，通过设定pwszHeaders设定cookie头部。客户程序应该在重新发送请求前清除所有cookie。

The client application should also change the cookie header when the request has been redirected. To change the cookie on redirected requests, the client specifies a callback function withWinHttpSetStatusCallback that responds to the redirect callback case. The callback handler should clear the cookie previously sent on the request by callingWinHttpAddRequestHeaders. For more information about removing cookie headers, seeRemoving Cookie Headers.

客户程序也可以在请求被重定向后改变cookie头部。要这么做，客户端要利用WinHttpSetStatusCallback函数设定一个回调函数。回调函数首先通过调用WinHttpAddRequestHeaders清除掉所有跳转前的cookie。详情参见Removing Cookie Headers。

Manual and Automatic Cookie Handling

手动自动结合

WinHTTP client applications can combine the WinHTTP automatic cookie handling mechanism with manual cookie handling. The application adds custom cookies to the automatically generated cookie header before sending the request with theWinHttpSendRequest function. The custom cookie should be the first cookie header in the request for the WinHTTP API to properly cache the cookie. The client application should also remove cookies sent on previous requests before resending a request on the same request handle. For more information, see Removing Cookie Headers.

WinHTTP客户程序可以把自动处理和手动处理结合起来。在调用WinHttpSendRequest函数发送前，程序可以把定制的cookie添加到自动生成的cookie头部。客户cookie就变成第一个WinHTTP API 请求和缓存时的cookie。客户程序也要在重发数据前清除已经发送过请求数据的句柄上的cookie。

Cookies added to a request before the call to WinHttpSendRequest are included in all WinHTTP requests sent on behalf of the nextWinHttpSendRequest andWinHttpReceiveResponse calls. The client application may need to clear the cookie header when the request has been redirected. To clear the cookie on redirected requests, the client specifies a callback function withWinHttpSetStatusCallback that responds to the redirect callback case. The callback handler should clear the cookie that was previously sent on the request by callingWinHttpAddRequestHeaders. The callback function may not set new custom cookies on the redirect callback. The client must wait forWinHttpReceiveResponse to complete before adding new cookies for the nextWinHttpSendRequest call.

在调用WinHttpSendRequest前cookie已经被添加进去了，这些请求会在后续的WinHttpSendRequest 和WinHttpReceiveResponse 发出。当请求被重定向后客户端也要清除cookie头部。要清除重定向后的请求中的cookie，客户端通过WinHttpSetStatusCallback函数指定回调函数来应对重定向这种情况。回调 函数应该清除之前请求中由WinHttpAddRequestHeaders设定的cookie回调函数也可以不设置新的客户cookie。客户端必须等待WinHttpReceiveResponse结束后才能添加新的cookie，然后再通过WinHttpSendRequest发送。

Removing Cookie Headers。

删除Cookie头部

The WinHTTP client application may need to clear the existing request cookie before resending a request to prevent cookies that were sent on previous requests from being sent again on the current request; for more information, see the following Note. Also be aware that Cookies do not have to be cleared before the first request is sent on the request handle. The client can clear existing cookies by callingWinHttpAddRequestHeaders with an empty cookie header in the pwszHeaders parameter and the WINHTTP_ADDREQ_FLAG_REPLACE flag set in thedwModifier parameter. The following code example shows how to clear the cookie header on the request.

WinHTTP客户端有时需要在重新发送请求前清除现有请求cookie，这样可以旧的cookie再次被发送；详情参加后续的注意事项。另外值得注意的是Cookie也不是非要在第一个请求通过请求句柄发送前被清除。客户端可以通过调用WinHttpAddRequestHeaders清除现有cookie，只要把代表cookie头部信息的pwszHeaders参数设为空，把dwModifier参数设为WINHTTP_ADDREQ_FLAG_REPLACE就可以了。下面代码展示了如何清除请求中的cooke头部。

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

The WinHTTP API has different cookie handling behaviors for versions of the operating system earlier than Windows XP with Service Pack 2 (SP2) and Windows Server 2003 with Service Pack 1 (SP1).

在Windows XP SP2以前和Windows 2003 Sp1之前的操作系统中，WinHTTP API有不同的cookie处理方式。

Windows XP SP2 和之后版本以及 Windows Server 2003 SP1 和以后版本: 

The WinHTTP API clears all cookies sent on previous requests for the request handle. The client can manually add new cookie headers before each call to WinHttpSendRequest. If the automatic cookie handling functionality of the WinHTTP API has not been disabled, the WinHTTP API will append the new cookie header (or add a new cookie header if the client application did not add one manually) with the cookie from the server.

WinHTTP API清除请求句柄上所有之前发送请求中cookie。客户端可以在每次调用WinHttpSendRequest前手动添加新的cookie头部。如果自动模式没被禁用，WinHTTP API将会自己添加一个新的从服务器获取的cookie头部（或在客户程序没有手动添加时添加一个新的cookie头部）

Windows XP with SP2 and Windows Server 2003 with SP1:  

The WinHTTP API does not clear the request cookie header after WinHttpReceiveResponse completes. Cookies sent in previous requests will be resent in subsequent calls toWinHttpSendRequest. The WinHTTP client application should clear existing cookies headers before resending a request on the request handle.

在调用WinHttpReceiveResponse完成后，WinHTTP API 不会清除cookie头部。在后续调用WinHttpSendRequest重新发送之前请求中发送过的Cookie。在请求句柄上重新发送请求前，WinHTTP客户端程序应先清除现有cookie头部。