
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:
- Fast alternative to CGI
- Seven different types of
extensions (filters and generators)
- Over 40 server-internal functions
exposed for direct use by extensions (no callbacks needed)
- Built-in optimized HTML
forms decoder, which supports all types of
form encoding (including uploaded files).
- Microsoft
ISAPI-ISA compatibility
mode; can run ISAs on WebSite.
- Built-in image mapper
- Direct access to all relevant transaction variables without using
function calls
- FaultGuard prevents server failures due to exceptions
in extensions
- WSAPI support functions are accessible to applications
running in ISAPI-ISA
compatibility mode.
- Generator extensions may be either registered and
preloaded, or load-on-demand.
- Buffered network I/O eliminates the need for read/write loops
- Fast memory-mapped file-to-net and net-to-file I/O
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.