How To Implementing Cookies In ISAPI (168864)

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:

http://msdn.microsoft.com/library/psdk/iisref/isre9uur.htm

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.