WebSite
WebSite API 1.1 SDK
Introduction and Overview

Rev 13-Apr-96

Status of This Document

This document describes WSAPI/1.1, which is supported by WebSite Professional. Extensions developed under WSAPI/1.0 will operate with WSAPI/1.1 as long as the extension does not do strict version binding. In addition, ISAs developed for Microsoft ISAPI/1.0 will work with WSAPI/1/1.

WSAPI Features

The WebSite API is a rich set of tools with which you can extend the capabilities of WebSite Pro to meet your needs. WSAPI's main features are:

Documentation Map

The WSAPI SDK documentation is organized to allow you to come up to speed as quickly as possible, and to provide you with fast access to reference information while you develop your extension. We suggest you spend a short bit of time reading this page, the General Information page, and the Extension Details page. If you have ISAPI-ISA extensions to run on WebSite Pro, and/or you're interested in upgrading them to use WSAPI, read the ISAPI Compatibility page. Then scan read the Functions and Transaction Context pages.

Finally, and this is the most important, build the example that most closely corresponds to the extension you want to write and become familiar with it. Play with it using your development environment's debugger. You can set it up to start or attach to the server as the host application for your DLL. Perhaps you can cut your code into the example, saving you time and trouble.

What is WSAPI?

The WebSite Application Programming Interface (WSAPI) provides a comprehensive set of tools with which you can extend the capabilities of WebSite Pro. Extensions are Windows dynamic link libraries (DLLs) which are loaded at the time that WebSite Pro starts up, and which provide services and features not present in WebSite Pro itself. This API has already been implemented as part of the development effort for WebSite Professional.

The following is a simplified block diagram of the WebSite Pro architecture, showing the various WSAPI extensions, and how they relate to the server's operation.

This is a client-side image map

What are the Goals of WSAPI?

The chief design goal for WSAPI is to provide a high-level of intimacy between the extension(s) and the server itself. The interface is not intended to be a cross-product or cross-platform standard, rather, it is designed to provide comprehensive access to WebSite Pro's internal services and data, and to maximize efficiency by minimizing layering. Current and future CPU technology depends heavily on instruction stream caching. Proliferation of function calls can degrade the overall performance of an application. Using function calls to access data is a particularly poor practice in this regard.

In addition, WSAPI is designed to provide control over the server's handling of Hypertext Transfer Protocol (HTTP) request/response process at several points in that process. It is not simply a fast CGI alternative. With WSAPI you can interpose your own functionality for the entire request, access control, authentication, document post-processing, error handling, logging, and, of course, CGI-like programmatic document generation.

Finally, WSAPI includes a compatibility interface for the Process Software/Microsoft Internet Server Application Programming Interface (ISAPI). Support is limited to Internet Server Applications; ISAPI filters are not supported. We provided this interface so that you can run existing ISAPI-ISA applications with WebSite and still use the rich set of capabilities in WSAPI. You can easily adapt an ISAPI application to use WebSite Pro's large set of server support functions such as the forms decoder, and you can use WSAPI's structured exception handling to streamline your error recovery and make it more robust.

Intended Audience

This document, and WSAPI itself, is written for advanced-level C and C++ programmers who have experience with multithreading, synchronization, dynamic link libraries, structured exception handling, the Windows NT system architecture, and the Win32 API. The writing style is purposely terse. We understand that advanced and expert level programmers just want the facts in quickly accessible, structured format.

Extension Types

WSAPI provides seven extension types:

Generator
Similar to a CGI program. Called via a special URL or mapped media content type. Responsible for generating a document for the response. May be pre-loaded or loaded on demand. A generator may use WSAPI's built-in forms decoder and image mapper to simplify forms processing and image map handling.

ISAPI-ISA Generator
Generator written to the Microsoft Internet Server Application Programming Interface (ISAPI) specification. Load on demand only. May be easily upgraded to use WSAPI features such as the form decoder and image mapper.

Pre-Processor
Called immediately after the server has processed the HTTP request headers and before it has done anything else. Can be used to alter the request before the rest of the server sees it.

Authenticator
Called when the server needs to authenticate a user. May be used to provide authentication via external databases, the NT domain, and so forth.

Post-Processor
Called when the server has nearly completed a document or CGI request. Can be used to alter the response document before it is sent to the browser. WebSite Pro's server-side include (SSI) features are implemented as a WSAPI post-processor.

Error Handler
Called whenever the server is about to send an HTTP response other than 200 OK. Can be used to send custom error responses for things like Not Found.

Logger
Called after the transaction has been completed (and the socket has been closed), but before it has logged the transaction. Can be used to generate special logs, log to a database, and so forth.

Examples Provided with the SDK

The WebSite API Software Development Kit, provided with WebSite Professional, contains examples written in C that illustrate usage of each of the extension types. Sources are provided, and the comments at the beginning of each sample describe the extension itself, usage, and installation. Examples include:

formdump
This is a generator extension that returns a HEX/ASCII dump of the contents of a form. This illustrates both the generator extension and the use of the WSAPI form decoder. You can POST to this extension from forms that use either the older URL-encoded or the new multipart/form-data form encoding. The form decoder hides the differences. You can even POST a file upload.

cookie
This is a pre-processor extension. It scans the request for the presence of a persistent-state cookie, and if none is present, it causes the response to include a new cookie. The new cookie has a lifetime of 24 hours, and a unique identifier that could be used to track unique visitors in a logger extension. The SDK also includes a companion generator sample, ckshow, that can be used to see the cookies that your browser sends. This sample is included so you can verify that the cookie is being sent and used without a network sniffer.

ckshow
This is a generator extension that echoes all cookies back to the browser. Not too useful, but it shows you that the cookie preprocessor really did set a cookie.

notfound
This is an error extension that shows how to send back a custom error response for a 404 not found. You can easily add your own features to this sample.

olewsapi
This is an adaptation of the OLEISAPI example provided with the Microsoft Internet SDK. This version has several corrections and enhancements; see the comments at the beginning. Note that OLE is not truly multithreaded, so this example (like the Microsoft one) serializes all transactions. Thus this is a possibly interesting demonstration, but not very practical.

pagecnt
This is a post-processor extension. It implements a server-side include feature that allows you to keep page counters in an HTML document without running a CGI script. It is actually the pagecounter portion of the full WebSite Pro server-side include DLL (without the support for the new file= option). This example illustrates a number of valuable Win32 techniques that you can use to maximize the efficiency of extentions in general.

referer
This is a logging extension. It implements a new log containing:

sysuser
An example authentication extension that uses the native NT user database for authentication while still maintaining WebSite Pro's URL-based access control. The Win32 API calls are limited to processes with extra privileges, so this must run with a privileged server.

A Word From the Developer

Prior to designing WSAPI in August 1995, I researched a number of alternatives such as DDE, OLE, and named pipes, in a quest to protect the server's internals from corruption by extensions. In the end, I concluded that it was possible to achieve the efficiency and flexibility I wanted only with DLLs. Microsoft (ISAPI) and Netscape (NSAPI) have reached the same conclusion.

I cannot stress enough that you need experience in programming multithreaded applications, how DLLs work in a multithreaded Win32 environment, structured exception handling, and synchronization issues (using critical sections, mutexes and semaphores). The server makes full use of all of these Win32 services, and its proper operation (and that of your extensions) demands your familiarity with them.

A Word From O'Reilly Tech Support

While the FaultGuard feature will protect the server from exceptions in your DLL code, there is no way to protect the server from runaway loops that cause a request to hang and burn CPU time or wild stores in your code that corrupt the server's internal data. This means that you hold the server's reliability in your hand when you write an extension. For this reason, O'Reilly Technical Support may ask you to disable all extensions while handling a problem that you feel is with the server itself. In addition, we cannot provide instructional services for inexperienced programmers, nor can we assist in detailed debugging of WSAPI extensions. Please keep these issues in mind when deciding whether to implement a WSAPI extension. With enough memory, a CGI program can be started in 0.1-0.2 seconds.

Additional Information

Your most vital reference is the Hypertext Transfer Protocol Specification, 1.0 (HTTP/1.0). This document describes the protocol used between Web clients and servers. Since you will be extending a server, it is vital that you understand the details of the interaction between a server and its clients. One way to get some familiarity is to turn on HTTP Protocol and Dump Sent Data tracing in WebSite Pro (on the Logging page of the server's property sheet). Then use a browser to access some documents and CGI programs. Stop the server and look at server.log. The trace data will show you the contents of the messages that flow between the client and server for the operations you wish to perform.


[email protected]

Copyright © 1994-96 O'Reilly & Associates, Inc. All Rights Reserved. O'Reilly Software Online, WebSite Central, WebSite, and WebSite Professional are trademarks of O'Reilly & Associates, Inc. FaultGuard is a trademark of Robert B. Denny.

All other names are the trademarks of their respective companies.