
This page describes each of the seven types of extensions that WSAPI supports. In order to understand the interaction of these extensions with WebSite Pro, refer to the diagram below which shows a simplified view of WebSite Pro's internal architecture and shows the location of each extension type. Before attempting to develop an extension, be sure to read and thoroughly understand the example supplied with WebSite Professional for the particular extension type you are developing.
Generators, as their name suggests, are used to create the content (document) returned in response to a request. Needless to say, a generator can do anything else in the process. It is responsible for returning something to the client, even if it is an HTTP error response, redirection, or even a "use local copy" response. The generator is responsible for calling the WSAPI functions that send the HTTP headers and the body. The server does nothing in this regard. At a minimum, the generator must fill in the appropriate fields in the transaction context (TCTX), call send_http_header(), and then transmit the body of the response using the nwrite() and/or nwritef() functions. Once the response has been sent to the client, the generator simply exits. See the documentation on send_http_header() for information on which TCTX fields are needed and how to use them.
Use the following URL syntax to access a load-on-demand generator extension:
http://x.y.z/gen-dll-url-pathfor example
http://solo.dc3.com/utilities/clock.wsaNote that the DLL has a name ending in .wsa instead of .dll. The server recognizes load-on-demand generators by looking for a media content type of wwwserver/wsapi. As shipped, WebSite Pro's content type map relates the file extension .wsa to wwwserver/wsapi. If you want all DLLs within your document URL space to be treated as generators (and never downloaded), then you can map .dll as wwwserver/wsapi. Never do this if any DLL could be used as a scripting engine! Someone could feed arbitrary commands to it via the query string, opening a serious security hole. In other words, don't do something like:
http://a.b.c/foo/perl.wsa?/bar/myscript.pl <---NO!
Someone could send a URL with a direct execute query string and do arbitrary things to your system.
If the generator is some sort of scripting engine, such as a perl or basic interpreter, the URL target should be the file containing the script and not the DLL. Do not be tempted to use the DLL as the target with the script file in the query string! It opens a serious security hole. In fact, don't even permit the scripting engine DLL to be web-visible.
WSAPI supports file associations for load-on-demand generators. For example, you can associate the file type .plx, calling it a Web server perl script, with a WSAPI-compatible perl interpreter DLL. Then tell WebSite Pro that .plx has a media content type of wwwserver/wsapi.
The file association can point to the DLL anywhere on any disk, it does not (and should not) need to be in any web-visible directory. Nor does it need to be recognized as wwwserver.wsapi by the server. Seeing that the script is a WSAPI executable is enough. The server will use the file association to locate and load the interpreter, and the interpreter can get the script's name by calling get_server_variable() for the SCRIPT_NAME variable and translating to physical file pathname using url_to_file(). With file associations, the example above can be implemented (safely) as:
http://a.b.c/bar/myscript.plx
NOTE: The Windows 95 options property sheet for making file extensions doesn't permit associations with anything it doesn't think is executable. An easy way around this is to rename the DLL as .exe, associate to it, then rename it back to .dll using the Explorer. The Explorer will fix-up the association to point to the new name.
Use the following URL syntax to access a registered generator extension:
http://x.y.z/~wsapi/gen-namefor example
http://solo.dc3.com/~wsapi/fd
The special path element ~wsapi tells WebSite Pro that the next path element, gen-name, is the name of the generator (not necessarily the physical file name of the DLL, see Installation below).
Up to 32 registered generators may be installed at a time. To install a generator, we recommend that you first copy the DLL to the server executable's directory. Then use the Registry editor to open the key
HKEY_LOCAL_MACHINE\SOFTWARE\Denny\WebServer\CurrentVersion\CGI\DLL
Add a new key whose name is the name you want to appear in URLs that access the generator. This does not need to be related to the physical name of the DLL file itself. Then open this key and add a string (REG_SZ) value named ExtCGIDll, the value of which is the file name of the generator DLL. This may be a full pathname if the DLL is located somewhere other than in the directory where the server executable httpd32.exe is located. Then add another string (REG_SZ) value named ExtCGIEntry, the value of which is the name of the action entry point to be called by WSAPI.
The return value from a generator extension is ignored.
It is sometime useful for a generator to use extra header information that may have been supplied by the client (browser) with the request. For example, if you have given a Netscape cookie to the user's browser, the cookie will be included in all appropriate requests sent by that browser and appear in the extra headers. You can access the extra header information in the transaction context (TCTX) via the num_req_xhdr and req_xhdr[] fields (see wsapi.h). The num_req_xhdr field contains the number of extra headers present in the request, and req_xhdr[] contains an array of key-value pairs for each extra header. The keys are the field labels exactly as they appear in the HTTP header of the request, with no changes to capitalization or character conversions.
A generator can add extra headers to the response. These will be seen by the browser/client. This is mostly useful for non-browser clients you may implement. It can also be used to send Netscape cookies. You can add extra request headers by using the num_req_xhdr and req_xhdrs[] fields in the transaction context (TCTX). The array is limited to MAX_EXT_HEADERS items (see wsapi.h), and there may already be extra headers present, coming from the browser. For example:
TCTX *tp;
...
tp->rsp_xhdr[tp->num_rsp_xhdr].key = wsapi_strdup("X-My-Stuff");
tp->rsp_xhdr[tp->num_rsp_xhdr++].value = wsapi_strdup("Whatever");
Notice the autoincrement of the num_req_xhdr field in the second store statement. This bumps the extra header count. The server will free the strings in the extra header tuples during its request cleanup processing.
Use the following URL syntax to access a an ISAPI-ISA generator extension:
http://x.y.z/isa-dll-url-pathfor example
http://solo.dc3.com/utilities/ticker.isaNote that the DLL has a name ending in .isa instead of .dll. The server recognizes ISAPI-ISA generators by looking for a media content type of wwwserver/isapi. As shipped, WebSite Pro's content type map associates the file extension .isa to wwwserver/isapi. If you want all DLLs within your document URL space to be treated as ISAPI generators (and never downloaded), then you can map .dll as wwwserver/isapi. Never do this if any DLL could be used as a scripting engine! Someone could feed arbitrary commands to it via the query string, opening a serious security hole. In other words, don't do something like:
http://a.b.c/foo/perl.isa?/bar/myscript.pl <---NO!
Someone could send a URL with a direct execute query string and do arbitrary things to your system.
If the generator is some sort of scripting engine, such as a perl or basic interpreter, the URL target should be the file containing the script and not the DLL. Do not be tempted to use the DLL as the target with the script file in the query string! It opens a serious security hole. In fact, don't even permit the scripting engine DLL to be web-visible.
File Associations
WSAPI's ISAPI compatibility mode supports file associations for ISAs. For example, you can associate the file type .plx, calling it a Web server perl script, with an ISAPI-compatible perl interpreter DLL. Then tell WebSite Pro that .plx has a media content type of wwwserver/isapi.
The file association can point to the DLL anywhere on any disk, it does not (and should not) need to be in any web-visible directory. Nor does it need to be recognized as wwwserver/isapi by the server. Seeing that the script is a WSAPI executable is enough. The server will use the file association to locate and load the interpreter, and the interpreter can get the script's name by calling the ISAPI GetServerVariable() function for the SCRIPT_NAME variable and translating to physical file pathname using the ServerSupportFunction(). With file associations, the example above can be implemented (safely) as:
http://a.b.c/bar/myscript.plx
NOTE: The Windows 95 options property sheet for making file extensions doesn't permit associations with anything it doesn't think is executable. An easy way around this is to rename the DLL as .exe, associate to it, then rename it back to .dll using the Explorer. The Explorer will fix-up the association to point to the new name.
Path Info and Path Translated in ISAPI
ISAPI 1.0 does not properly implement extra path info. It puts the original target file pathname (URL and physical) into these variables in both the ECB and the data used for GetServerVariable(). Therefore you cannot use extra path information in ISAPI-ISAs. Do not make use of the contents of path info and path translated in ISAPI 1.0. Microsoft will certainly change this in a subsequent release. WSAPI's ISAPI compatibility mode implements this identically to the ISAPI in Microsoft's server for compatibility reasons (it is required by the ISAPI based perl5 engine in the Resource Kit).
The logging extension is used to augment or replace WebSite Pro's access logging features. It is called when a request is complete, just before WebSite Pro's internal logging functions are to be run. The logger can control whether the server itself logs the transaction. This can be useful for trapping certain classes of events and logging them separately, or replacing the internal logger entirely.
To install a logging extension, we recommend that you first copy the DLL to the server executable's directory. Then use the Registry editor to open the key
HKEY_LOCAL_MACHINE\SOFTWARE\Denny\WebServer\CurrentVersion\Logs
Change the ExtLogDll value to the file name of your logger DLL. This may be a full pathname if the DLL is located somewhere other than in the directory where the server executable httpd32.exe is located. Then change the ExtLogEntry value to the name of the action entry point in your DLL.
If the logger returns FALSE, the transaction is not logged by WebSite Pro's internal logger. If the logger returns TRUE, WebSite Pro logs the transaction as usual.
The WSAPI function wsapi_log_event() may be used to log events in the server's log (server.log) and if on NT, in the NT event log. This is not the same as logging into the access log, but can be useful for logging special events from the logging extension. Do not log all transactions into the server or NT event logs!
The logging extension is run in the context of the thread that handled the request, but is run after the socket has been closed (unless keep-alive is in effect). The effect, whether or not keep-alive is in effect, is that the logger does not affect the response time for the request as seen from the browser. It does, however affect the time taken and CPU load to service the request.
The error extension can be used to augment or replace WebSite Pro's internal HTTP exception reporting mechanism. A typical use would be to replace the response for a 404 Not Found condition with a custom HTML message to the browser. Most exceptions in WebSite Pro end up in the die() function, which calls the error extension, if installed. Therefore, do not call die() from an error extension!
If you decide to send your own HTTP response, you can fill in the appropriate fields in the transaction context (TCTX), call send_http_header(), and then transmit the body of the response using the nwrite() and/or nwritef() functions, then return TRUE to indicate that you handled the exception yourself.
To install an error handler extension, we recommend that you first copy the DLL to the server executable's directory. Then use the Registry editor to open the key
HKEY_LOCAL_MACHINE\SOFTWARE\Denny\WebServer\CurrentVersion
Change the ExtErrDll value to the file name of your error handler DLL. This may be a full pathname if the DLL is located somewhere other than in the directory where the server executable httpd32.exe is located. Then change the ExtErrEntry value to the name of the action entry point in your DLL.
If the error extension returns TRUE, the server will not send any response, assuming that the extension sent the response instead. If the extension returns FALSE, the server assumes that the extension did not want to handle the exception and sends the normal HTTP response for that type of extension.
Post-processors are used to modify fetched documents (see Modifying Documents below). They cannot be used to modify the results of a CGI program, WSAPI generator extension or an automatically generated directory listing. Up to thirty two post-processors may be installed at a time, each associated with a particular MIME content type. See Content Types below. Post-processors are called immediately before the server starts streaming the document back to the client. At this time, all of the system, request, and response fields of the transaction context (TCTX) are valid. Multiple post-processors can operate on a single requested document if they change the content type during document modification, as described in Content Types below.
In addition to content type specific post-processors, you can install a global post-processor, which is called after all of the others. It is designated by a special content type of */*. The global post-processor can be used to perform post processing on all documents, regardless of their content type.
HKEY_LOCAL_MACHINE\SOFTWARE\Denny\WebServer\CurrentVersion\PostProc\Type
Add a new key whose name is the MIME content type for which you are installing the post-processor. Use */* for the global post-processor. Then open this key and add a string (REG_SZ) value named ExtProcDll, the value of which is the file name of the post-processor DLL. This may be a full pathname if the DLL is located somewhere other than in the directory where the server executable httpd32.exe is located. Finally, add another string (REG_SZ) value named ExtProcEntry, the value of which is the name of the action entry point to be called by WSAPI.
The return value from a post-processor is ignored.
To modify a document, create a new temporary file with the delete on close attribute. Use the WSAPI get_temp_name() function to get a unique temporary name and the temp_path field in the transaction context to get the directory path to the server's temporary directory (see the sample post-processor for details). Rewind the tp->hOutFile file and read from it, performing your processing and writing to the new temporary file. Once you have completed processing the document, do a CloseHandle() on tp->hOutFile. Then rewind the new temporary file containing the processed document and replace tp->hOutFile with its handle. The server will close the processed document file after it has streamed it to the client, at which time it will be automatically deleted by the operating system (since it was created with the delete-on-close attribute).
When you modify a document you should always update tp->last_modified to the current system date/time. This prevents browsers' caching from being fooled into returning an old copy of the document. Finally, call GetFileSize() on the new temporary file and update tp->content_length to reflect the correct size of the processed file.
See the sample for further details. Also, see the Content Types section below for information on how to operate on a single document with multiple post-processors.
Each post-processor is associated with a particular MIME content type. This is deceptively powerful. You can define your own content type and associate it with special file extensions. The post-processor will be called for any document/file with that extension, and it can change the content type to one that the browser is likely to understand. Furthermore, once a particular post-processor runs, if the content type changed, the server will run the post-processor for the new content-type if one exists. None of the intermediate content types will ever be seen by the browser. They are used simply to activate and sequence the various post-processors.
The special content type */* designates a global post-processor. This is called for all documents, regardless of their content type, and it is called after any type-specific post-processors have been called as described above.
The post-processor can add extra headers to the response. These will be seen by the browser/client. Adding extra headers is mostly useful for non-browser clients you may implement. It can also be used to send Netscape cookies. You can add extra request headers by using the num_req_xhdr and req_xhdrs[] fields in the transaction context (TCTX). The array is limited to MAX_EXT_HEADERS items (see wsapi.h), and there may already be extra headers present, coming from the browser. For example:
TCTX *tp;
...
tp->rsp_xhdr[tp->num_rsp_xhdr].key = wsapi_strdup("X-My-Stuff");
tp->rsp_xhdr[tp->num_rsp_xhdr++].value = wsapi_strdup("Whatever");
Notice the autoincrement of the num_req_xhdr field in the second store statement. This bumps the extra header count. The server will free the strings in the extra header tuples during its request cleanup processing.
The authenticator extension is called whenever the request's URL path has users/groups access control set. It is also called if a WSAPI extension uses the evaluate_access() function. The transaction context (TCTX) fields of interest are auth_name, auth_type, user, and pass. The authenticator does not provide access control! Instead, it uses the TCTX information to determine if the user identification info in the request corresponds to a valid user, then it replaces the user_to_check field in the TCTX with a dummy username which the server uses for access control. This gives you a very flexible and powerful mechanism for authentication while using the server's internal access control features. You use the server's property sheet to set up the dummy realms and username(s), and all your authenticator has to do is determine whether the real user can act as a dummy. Only one authenticator may be installed.
To install an authenticator, we recommend that you first copy the DLL to the server executable's directory. Then use the Registry editor to open the key
HKEY_LOCAL_MACHINE\SOFTWARE\Denny\WebServer\CurrentVersion\Authentication
Change the ExtAuthDll value to the file name of your authenticator DLL. This may be a full pathname if the DLL is located somewhere other than in the directory where the server executable httpd32.exe is located. Then change the ExtAuthEntry value to the name of the action entry point in your DLL.
The authenticator may return one of three values (defined in wsapi.h):
| Return Value | Description |
| AUTH_ACCEPT | The identification information in the request is acceptable, and the TCTX user field contains the username to use for access control. |
| AUTH_REJECT | The identification information in the request is unacceptable. The server will immediately return a 401 Not Authorized response, causing the browser to redisplay the username/password dialog. |
| AUTH_INTERNAL | An authenticator no-op. The server will use its internal authenticator. |
Don't underestimate the power of this extension. You can do most
anything you want. Look carefully at the sample authenticator
provided with WebSite Pro. Note that you have control over the realm
and dummy username(s) that apply to the protected URL. The realm
name shows in the username/password box, so you can prompt
browser users. Use multiple dummy user names to provide different
levels of access, perhaps through group memberships in dummy groups.
Provide multiple resolutions of real users to dummy usernames.
The pre-processor extension is called immediately after the server has received and interpreted the HTTP request and before it makes any decisions as to its actions for the request. At this time, all of the system- and server-related fields in the transaction context are valid, as are all of the request-related fields. The pre-processor is called for all received requests, not just for document fetches. You can do most anything at this point, including modifying the URL or even completing the request entirely in your extension, bypassing the rest of the server completely. Only one pre-processor may be installed at a time.
To install a pre-processor, we recommend that you first copy the DLL to the server executable's directory. Then use the Registry editor to open the key:
HKEY_LOCAL_MACHINE\SOFTWARE\Denny\WebServer\CurrentVersion
Change the ExtPreDll value to the file name of your pre-processor DLL. This may be a full pathname if the DLL is located somewhere other than in the directory where the server executable httpd32.exe is located. Then change the ExtPreEntry value to the name of the action entry point in your DLL.
Normally, your pre-processor should return FALSE. If your pre-processor (in this case, a surrogate server!) handled the request completely, requiring no further action on the part of the server, return TRUE. This will cause the server to skip all of its internal logic, close the connection to the browser, and log the transaction. The only other extension that will be called is the logger.
The pre-processor can add extra headers to the request, making it look to the rest of the server as though the browser generated the extra header(s). These may be used by other extensions, usually a generator or post processor, to modify their behavior. You can add extra request headers by using the num_req_xhdr and req_xhdrs[] fields in the transaction context (TCTX). The array is limited to MAX_EXT_HEADERS items (see wsapi.h), and there may already be extra headers present, coming from the browser. For example:
TCTX *tp;
...
tp->req_xhdr[tp->num_req_xhdr].key = wsapi_strdup("X-My-Stuff");
tp->req_xhdr[tp->num_req_xhdr++].value = wsapi_strdup("Whatever");
Notice the autoincrement of the num_req_xhdr field in the second store statement. This bumps the extra header count. The server will free the strings in the extra header tuples during its request cleanup processing. The pre-processor can also add output (response) extra headers, see Output (Response) Extra Headers above.
website-support