WSAPI support for Delphi 2.0
This is a rudimentary framework for building WSAPI applications
using Delphi 2.0.

Port and Extras by Paul Gallagher <paulpg@ozemail.com.au>
E-mail comments and suggestions. Most welcome!

Revisions:
  29-Jan-97 - paulg - added more samples, incl. SysUser!
  15-Aug-96 - paulg - first release

Contents of this file
  1. The kit
  2. Warnings and Limitations
  3. Basic setup & testing
  4. Samples
  4.1 Ckshow Generator Sample
  4.2 Cookie Pre-processor Sample
  4.3 Formdump Generator Sample
  4.4 Notfound Error Handler Sample
  4.5 Unauth Error Handler Sample
  4.6 Sysuser Authorisation Sample
  5. Improvements Pending

T H E   K I T
=============
Basically, this is what's included at this stage:

  wsapi\lib\wsapi.pas
  wsapi\lib\wsapi.dcu (compiled)
    - Pascal unit to include in your applications. This defines all
      of the WSAPI functions and constants (the equivalent of WSAPI.H)

  wsapi\examples\ckshow\
    - Delphi version of the Ckshow generator included in the WSAPI
      developer's kit. Comprises:
        ckshow.dpr - project file
        ckshow.res/dof - Delphi resource/option files
        ckshow.dll/wsa - compiled project (same file, different extensions)

  wsapi\examples\cookie\
    - Delphi version of the Cookie pre-processor sample included in the WSAPI
      developer's kit. Comprises:
        cookie.dpr - project file
        cookie.res/dof - Delphi resource/option files
        cookie.dll/wsa - compiled project (same file, different extensions)

  wsapi\examples\formdump\
    - Delphi version of the Formdump generator sample included in the WSAPI
      developer's kit. Comprises:
        formdump.dpr - project file
        formdump.res/dof - Delphi resource/option files
        formdump.dll/wsa - compiled project (same file, different extensions)
        atest.htm        - simple HTML page to invoke formdump.wsa

  wsapi\examples\notfound\
    - Delphi version of the NOTFOUND error handler sample included in the WSAPI
      developer's kit.
        notfound.dpr     - project file
        notfound.res/dof - Delphi resource/option files
        notfound.dll     - compiled project

  wsapi\examples\sysuser\
    - variant of the SYSUSER authentication module included in the WSAPI
      developer's kit - this one works! Comprises:
        sysuser.dpr     - project file
        sysuser.res/dof - Delphi resource/option files
        sysuser.dll     - compiled project

  wsapi\examples\unauth\
    - variant of the NOTFOUND sample, this one specifically intercepts 401
      authorisation requests and provides a custom return page.
        unauth.dpr     - project file
        unauth.res/dof - Delphi resource/option files
        unauth.dll     - compiled project
        401.htm        - sample 401 error page

W A R N I N G S  &  L I M I T A T I O N S
=========================================
WARNING! This software is hack-ware! No warranties etc, etc. In particular,
note that these Delphi WSAPI modules have not been tested or certified
for high-volume production environments. Use at your own risk.

Note on exception handling:
I have encountered problems when using exception handling blocks (try..except)
in the main exported function (usually "Process"). In the "unauth" example,
I liberally use exception handling in other routines without problems,
but to include it in "Process" breaks the routine (Try it yourself! Just
put a redundant try ...except around something and re-compile).
This has really got me stumped. Any thoughts? Please e-mail!

B A S I C    S E T U P   &   T E S T I N G
==========================================
Explode dwsapi.zip into a web-visble directory structure. Make sure
you re-create the directory structure.

To run generators, you'll find it easiest to setup a corresponding MIME type.
Go to the mapping tab of the WebSite Server Properties dialog box.
Check you have a content type of '.wsa' mapped to MIME content type
'wwwserver/wsapi'.

C K S H O W
===========
Ckshow is a simple generator that reports cookies held. Simply open
ckshow.wsa with your browser.

C O O K I E
===========
Cookie is a simple pre-processor that adds a unique cookie to any
client request that doesn't alreay have one.

WebSite is configured to use cookie pre-processor by modifying
some WebSite registry settings. Using RegEdt32, set:

  Key root : HKEY_LOCAL_MACHINE
  Key : \Software\Denny\WebServer\CurrentVersion
  Value : ExtPreDll
  set to : (full path to) wsapi\examples\cookie\cookie.dll
  Value : ExtPreEntry
  set to : GiveCookie (name of entry function)

You will then need to restart WebSite.

F O R M D U M P
===============
Formdump is a simple generator example.

Use your browser to load wsapi/examples/formdump/atest.htm (per WebSite of
course, not locally). Enter some details on the form and submit. 
The form is submitted to, and response is returned from formdump.wsa.
That's all folks!

N O T F O U N D
===============
Notfound is a simple error handler extension that handles 201 Not Found errors
and returns a custom form.

WebSite is configured to use notfound error handler by modifying
some WebSite registry settings. Using RegEdt32, set:

  Key root : HKEY_LOCAL_MACHINE
  Key : \Software\Denny\WebServer\CurrentVersion
  Value : ExtErrDll
  set to : (full path to) wsapi\examples\notfound\notfound.dll
  Value : ExtErrEntry
  set to : Process (name of entry function)

You will then need to restart WebSite.

Use your browser to access a non-existent page and see the custom message!

U N A U T H
===========
Unauth is a 401 Unauthorised error handler (not in the WSAPI dev kit - my own
addition). It is very similar to notfound, but is actually a usefull tool
as it stands. It allows you to provide a customised HTML file which will
be used in place of the standard "Unauthorised" message.

Configure WebSite to use unauth by modifying some WebSite registry settings.
Using RegEdt32, set:

  Key root : HKEY_LOCAL_MACHINE
  Key : \Software\Denny\WebServer\CurrentVersion
  Value : ExtErrDll
  set to : (full path to) wsapi\examples\unauth\unauth.dll
  Value : ExtErrEntry
  set to : Process (name of entry function)

Create an HTML file that is to be used in place of the standard unauthorised
message (it should be a full HTML document from <HTML> thru to </HTML>).

In the HTML file, you may use two special codes that will be substituted
with "real" values at run-time:

  %url% will be substituted with the URL of the page that faulted.
  %referer% will be substituted with the URL of the page that pointed to %url%

Note that these codes must be in lower-case. Now create a Registry entry
to tell unauth where to find this file.

  Key root : HKEY_LOCAL_MACHINE
  Create new Key : \Software\Denny\WebServer\CurrentVersion\ExtErrBodies
  Add Value : 401
  set to : (full path to your custom 401 error file)
            eg: d:\wsapi\examples\unauth\401.htm

S Y S U S E R
=============
Note: the user under which the web server is operating must be given
the privilege to "Act as part of the operating system". See user manager
and select the "Policies | User rights" menu - make sure you check the box
"Show Advanced User Rights" in the dialog displayed.

This will create a new Realm called Windows NT Users. Web logons will be
validated against accounts in the web servers domain, and then users will
all get the privileges of the user "SysUser".

I M P R O V E M E N T S   P E N D I N G
=======================================
Depending on how useful I find this *new* capability (and what sort of feedback
I get), I'll be making appropriate improvements to this kit.
Of course, this will involve testing the full range of WSAPI features (if
you look at WSAPI.PAS you'll notice I've only actively tested a handful
of core functions exported from httpd32.exe)

Please drop me a line at paulpg@ozemail.com.au with your thoughts and suggestions.

Regards,
Paul Gallagher
September 1996
