ISAPI Extensions: Servers
This article describes the MFC classes used in writing ISAPI server extensions. Topics include:
Classes Used in Writing an ISA
Server Entry-Point Functions
The EXTENSION_CONTROL_BLOCK Structure
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 illustrates how to use , , and .
Classes Used in Writing an ISA
To write an ISA in MFC, create a object. Each time the CHttpServer receives a client request, it creates a 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.
Server Entry-Point Functions
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: and . 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.
CHttpServer::GetExtensionVersion
When the server application is invoked for the first time, the server calls to perform two tasks:
Exchange version information
The default implementation of GetExtensionVersion checks the version number for which you are creating your server extension against the server’s version number.
Provide a short text description of the ISA
Override GetExtensionVersion to set the text string with your own description.
CHttpServer::HttpExtensionProc
The second CHttpServer member function to consider as an entry point is , 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 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 EXTENSION_CONTROL_BLOCK Structure
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 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...