Article ID: 168864
Article Last Modified on 8/18/2006
APPLIES TO
- Microsoft Internet Server Application Programming Interface 4.0
- Microsoft Internet Information Services 5.0
This article was previously published under Q168864
SUMMARY
Cookies are a means by which a server application can cause a client to return information to the server with each HTTP request. This can be used to maintain a state with the client across multiple requests. Cookies are sent as part of the HTTP header in a client request or server response, and an ISAPI extension or filter DLL can readily send and retrieve them. This article is not meant to be a complete reference for cookies; it explains the basics of implementing them with the Microsoft Internet Server Application Programming Interface (ISAPI). For more information on cookies, please see the References section of this article.
MORE INFORMATION
NOTE: Most of the code below is for an ISAPI DLL that does not use the MFC ISAPI classes or ISAPI Extension Wizard. For an ISAPI DLL that uses MFC, the functions called will be the MFC-wrapped versions. The syntax must be modified accordingly.
Sending Cookies
A cookie is sent to the client by the server in an HTTP "Set-Cookie:" header. This header can be added in an ISAPI filter with the AddResponseHeaders member function in the HTTP_FILTER_CONTEXT structure passed to the filter notification:
pFC->AddResponseHeaders(pFC, "Set-Cookie: Cookie1=Value1; path=/;\r\n",
0);
In the above example, "Cookie1" is the name of the cookie and "Value1" is the value of the cookie. The "path=/" attribute tells the client to return the cookie with all requests to that server. If unspecified, the client assumes the path to be the same as that of the requested resource.
NOTE: If you are adding the header within the SF_NOTIFY_SEND_RESPONSE handler, you should use the AddHeader member of the HTTP_FILTER_SEND_RESPONSE structure rather than AddResponseHeaders. For more information on AddResponseHeaders, see the Platform SDK Documentation or the following Microsoft Developer Network (MSDN) Web site:
A cookie can also be added as an additional header in a call to ServerSupportFunction from within an ISAPI extension:
char szHeader[]="Set-Cookie: Cookie2=Value2; path=/;\r\nContent-type:
text/html\r\n\r\n";
DWORD dwSize;
dwSize = strlen(szHeader);
lpECB->ServerSupportFunction(lpECB, HSE_REQ_SEND_RESPONSE_HEADER,
NULL, &dwSize, (unsigned long *)szHeader);
In an MFC ISAPI extension, headers should not be sent in this way; instead, add the cookie to the output stream with the AddHeader function:
char szHeader[]="Set-Cookie: Cookie2=Value2; path=/;\r\n";
StartContent(pCtxt);
AddHeader(pCtxt, szHeader);
Note that the content type does not need to be "text/html"; cookies will work for any content type.
Retrieving Cookies
A cookie is returned to the server by the client in an HTTP "Cookie:" header. Multiple cookies can appear in this header, separated by semicolons. This header can be retrieved in an ISAPI filter responding to the SF_NOTIFY_PREPROC_HEADERS notification using the GetHeader member function in the HTTP_FILTER_PREPROC_HEADERS structure:
DWORD WINAPI HttpFilterProc(HTTP_FILTER_CONTEXT *pFC,
DWORD notificationType, VOID *pvNotification)
{
HTTP_FILTER_PREPROC_HEADERS *pPH;
char szBuffer[4096];
DWORD dwSize=4096;
pPH = pvNotification;
pPH->GetHeader(pFC, "Cookie:", szBuffer, &dwSize);
return SF_STATUS_REQ_NEXT_NOTIFICATION;
}
Or, a cookie can be retrieved in either a filter or extension using the GetServerVariable member function in the HTTP_FILTER_CONTEXT and EXTENSION_CONTROL_BLOCK structures:
char szBuffer[4096];
DWORD dwSize=4096;
In a filter:
pFC->GetServerVariable(pFC, "HTTP_COOKIE", szBuffer, &dwSize);
Or, in an extension:
pECB->GetServerVariable(pECB, "HTTP_COOKIE", szBuffer, &dwSize);
Cookie Persistence
The cookies in the above examples will only be maintained by the client until the user exits the browser. The server can cause a cookie to be maintained by a browser for a longer period by specifying an "expires" attribute. This will cause the browser to store the cookie and continue returning it to the server with each request, until the cookie is expired:
pFC->AddResponseHeaders(pFC,"Set-Cookie: Cookie1=Value1;
expires=Fri 22-May-1998 13:00:00 GMT; path=/;\r\n", 0);
Additional Notes
- The use of cookies requires support from the client browser. If the browser does not support cookies, or if the user has disabled this support, features of your Web site that depend on cookies may not function properly. It is good practice to degrade gracefully in this situation.
- The number and size of cookies that can be stored on a client is not unlimited. Rather than storing bulk data on the client, it may be better to send a unique identifier that associates the client with data stored on the server.
- Cookies are transmitted in clear text over the Internet, and are fully exposed to tampering when stored on the client system. Therefore, sensitive information such as passwords, credit card numbers, and so forth should not be stored in them.
REFERENCES
For more information, please see the following sites:
The preliminary cookie specification:
RFC 2109 - HTTP State Management Mechanism:
Keywords: kbhowto KB168864
