HOWTO: Implementing Cookies In ISAPI

Last reviewed: September 24, 1997
Article ID: Q168864

The information in this article applies to:

Microsoft Internet Server Application Programming Interface (API)

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.

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:

   http://home.netscape.com/newsref/std/cookie_spec.html

RFC 2109 - HTTP State Management Mechanism:

   http://www.cis.ohio-state.edu/htbin/rfc/rfc2109.html

Keywords          : IISAPI
Technology        : kbInetDev
Platform          : NT WINDOWS
Issue type        : kbhowto

================================================================================

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.

Last reviewed: September 24, 1997
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.