Spaces:
Running
Running
| <!-- NOTE: This HTML is displayed inside the CHM file - hence some hrefs | |
| will only work in that environment | |
| --> | |
| <HTML> | |
| <BODY> | |
| <TITLE>Introduction to Python ISAPI support</TITLE> | |
| <h2>Introduction to Python ISAPI support</h2> | |
| <h3>See also</h3> | |
| <ul> | |
| <li><a href="/isapi_modules.html">The isapi related modules</a> | |
| </li> | |
| <li><a href="/isapi_objects.html">The isapi related objects</a> | |
| </li> | |
| </ul> | |
| <p><i>Note: if you are viewing this documentation directly from disk, | |
| most links in this document will fail - you can also find this document in the | |
| CHM file that comes with pywin32, where the links will work</i> | |
| <h3>Introduction</h3> | |
| This documents Python support for hosting ISAPI exensions and filters inside | |
| Microsoft Internet Information Server (IIS). It assumes a basic understanding | |
| of the ISAPI filter and extension mechanism. | |
| <p> | |
| In summary, to implement a filter or extension, you provide a Python module | |
| which defines a Filter and/or Extension class. Once your class has been | |
| loaded, IIS/ISAPI will, via an extension DLL, call methods on your class. | |
| <p> | |
| A filter and a class instance need only provide 3 methods - for filters they | |
| are called <code>GetFilterVersion</code>, <code>HttpFilterProc</code> and | |
| <code>TerminateFilter</code>. For extensions they | |
| are named <code>GetExtensionVersion</code>, <code>HttpExtensionProc</code> and | |
| <code>TerminateExtension</code>. If you are familiar with writing ISAPI | |
| extensions in C/C++, these names and their purpose will be familiar. | |
| <p> | |
| Most of the work is done in the <code>HttpFilterProc</code> and | |
| <code>HttpExtensionProc</code> methods. These both take a single | |
| parameter - an <a href="/HTTP_FILTER_CONTEXT.html">HTTP_FILTER_CONTEXT</a> and | |
| <a href="/EXTENSION_CONTROL_BLOCK.html">EXTENSION_CONTROL_BLOCK</a> | |
| object respectively. | |
| <p> | |
| In addition to these components, there is an 'isapi' package, containing | |
| support facilities (base-classes, exceptions, etc) which can be leveraged | |
| by the extension. | |
| <h4>Base classes</h4> | |
| There are a number of base classes provided to make writing extensions a little | |
| simpler. Of particular note is <code>isapi.threaded_extension.ThreadPoolExtension</code>. | |
| This implements a thread-pool and informs IIS that the request is progressing | |
| in the background. Your sub-class need only provide a <code>Dispatch</code> | |
| method, which is called on one of the worker threads rather than the thread | |
| that the request came in on. | |
| <p> | |
| There is base-class for a filter in <code>isapi.simple</code>, but there is no | |
| equivilent threaded filter - filters work under a different model, where | |
| background processing is not possible. | |
| <h4>Samples</h4> | |
| Please see the <code>isapi/samples</code> directory for some sample filters | |
| and extensions. | |
| <H3>Implementation</H3> | |
| A Python ISAPI filter extension consists of 2 main components: | |
| <UL> | |
| <LI>A DLL used by ISAPI to interface with Python.</LI> | |
| <LI>A Python script used by that DLL to implement the filter or extension | |
| functionality</LI> | |
| </UL> | |
| <h4>Extension DLL</h4> | |
| The DLL is usually managed automatically by the isapi.install module. As the | |
| Python script for the extension is installed, a generic DLL provided with | |
| the isapi package is installed next to the script, and IIS configured to | |
| use this DLL. | |
| <p> | |
| The name of the DLL always has the same base name as the Python script, but | |
| with a leading underscore (_), and an extension of .dll. For example, the | |
| sample "redirector.py" will, when installed, have "_redirector.dll" created | |
| in the same directory. | |
| <p/> | |
| The Python script may provide 2 entry points - methods named __FilterFactory__ | |
| and __ExtensionFactory__, both taking no arguments and returning a filter or | |
| extension object. | |
| <h3>Using py2exe and the isapi package</h3> | |
| You can instruct py2exe to create a 'frozen' Python ISAPI filter/extension. | |
| In this case, py2exe will create a package with everything you need in one | |
| directory, and the Python source file embedded in the .zip file. | |
| <p> | |
| In general, you will want to build a seperate installation executable along | |
| with the ISAPI extension. This executable will be built from the same script. | |
| See the ISAPI sample in the py2exe distribution. | |