This article describes the MFC classes used in writing ISAPI server extensions. Topics include:
For a detailed list of steps to create your ISAPI server extension, see Steps to Create a Typical ISAPI Extension.
For an introduction to HTTP servers, see the article Internet Server API (ISAPI) Extensions. For a comparison of ISAPI and CGI, see How Does ISAPI Compare with CGI?.
The MFC Internet sample program WWWQUOTE illustrates how to use CHttpServer, CHttpServerContext, and CHtmlStream.
To write an ISA in MFC, create a CHttpServer object. Each time the CHttpServer receives a client request, it creates a CHttpServerContext object. It passes a pointer to that object to the command handling function. The use of multiple CHttpServerContext objects permits the CHttpServer object to handle a single command from a single client to the server object. Because the server may be handling concurrent, multiple requests, more than one active CHttpServerContext object can be associated with a particular CHttpServer instance.
Use the MFC class CHttpServer to create and manage a server extension DLL. Your server extension DLL should expose two entry points as exported functions: CHttpServer::GetExtensionVersion and CHttpServer::HttpExtensionProc. An extension DLL generated by the ISAPI Extension Wizard will have a .def file that correctly exports these functions. The functions are implemented by MFC, which simply finds the single CHttpExtension instance in the DLL and calls its CHttpServer::GetExtensionVersion or CHttpServer::HttpExtensionProc implementation as appropriate.
When the server application is invoked for the first time, the server calls CHttpServer::GetExtensionVersion to perform two tasks:
The default implementation of GetExtensionVersion checks the version number for which you are creating your server extension against the server’s version number.
Override GetExtensionVersion to set the text string with your own description.
The second CHttpServer member function to consider as an entry point is CHttpServer::HttpExtensionProc, which is similar to the main function of an application. It uses callback functions to read client data and determine the action to be taken. Usually, you won’t take direct action with HttpExtensionProc because MFC automatically handles incoming client requests by sending them through a parse map. The parse map is used to identify which of your functions to call, and to extract the function parameters. For information on using the parse map macros, see the article ISAPI Extensions: Parse Maps.
When HttpExtensionProc finishes, it returns a value, which the server then formats and returns to the client. For a list of the values returned, see the description for HttpExtensionProc in the Class Library Reference.
The default implementation of HttpExtensionProc is recommended; however, you can override it to provide custom implementation. For example, you could override this function to allocate per-call data.
The HTTP server and the ISA communicate data through the EXTENSION_CONTROL_BLOCK structure. The information passed through the structure includes, for example, the raw query string, path information, method name, and translated path. MFC copies the EXTENSION_CONTROL_BLOCK pointer it receives from the server and passes it along in the CHttpServerContext object passed to command handling functions. Reference information about the EXTENSION_CONTROL_BLOCK structure, including a list of possible field values, is in the Class Library Reference.
See Also ISAPI Extensions: MFC Classes, ISAPI Extensions: Filters, Steps to Create a Typical ISAPI Filter, Internet: Where Is...