WebSite
WebSite API 1.1 SDK
Description of Extensions

Return to Overview
Rev 13-Apr-96

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.

This is a client-side image map

Generators

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.

Two Ways to Run Generators

A generator extension may either be registered and pre-loaded, or loaded on demand. Registered generators are loaded when the server starts and remain loaded for the lifetime of the server process. Load-on-demand generators are dynamically loaded when the server receives a URL that resolves to the generator DLL as a file, then unloaded when no more transactions are using them. Both are fully multithreaded.

Usage: Load-On-Demand Generators

Use the following URL syntax to access a load-on-demand generator extension:

    http://x.y.z/gen-dll-url-path
for example

    http://solo.dc3.com/utilities/clock.wsa
Note 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.

Usage: Registered/Preloaded Generators

Use the following URL syntax to access a registered generator extension:

    http://x.y.z/~wsapi/gen-name
for 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).

Installation of Registered Generators

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.

Return Value

The return value from a generator extension is ignored.

Input (Request) Extra Headers

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.

Output (Response) Extra Headers

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.


ISAPI-ISA Generators

WSAPI supports generators written to the Microsoft Internet Server Application Programming Interface (ISAPI). For more information on ISAPI, see the Microsoft Internet SDK and the ISAPI Compatibility page of this document. ISAPI generators can be easily modified to use WSAPI's large set of directly-callable support functions since WebSite Pro uses the address of the native WSAPI transaction control block as the connection ID field of the ISAPI extension control block.

Usage: ISAPI Compatibility Mode

Use the following URL syntax to access a an ISAPI-ISA generator extension:

    http://x.y.z/isa-dll-url-path
for example

    http://solo.dc3.com/utilities/ticker.isa
Note 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

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.

Installation

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.

Return Value

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.

Notes

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

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.

Installation

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.

Return Value

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

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.

Global Post-Processor

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.

Installation

Up to 32 post-processors 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\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.

Return Value

The return value from a post-processor is ignored.

Modifying Documents

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.

Content Types

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.

Output (Response) Extra Headers

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

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.

Installation

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.

Return Value

The authenticator may return one of three values (defined in wsapi.h):

Return ValueDescription
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.

Notes

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

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.

Installation

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.

Return Value

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.

Input (Request) Extra Headers

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