===========================================================================
=         README.TXT for sample DSAPI HTTP logging filter                 =
=               Copyright (c) 2000 Paul D. Ray                            =
===========================================================================
This file provides supplemental information about the sample code that 
accompanies the article entitled "Building a Filter to Support the W3C 
Extended Log File Format: An Introduction to the Domino Server API (DSAPI)" 
published in the September/October 2000 issue of THE VIEW (www.eview.com). 


===========================================================================
Installing the Filter
===========================================================================
Follow these steps to install the filter:

1) Copy the compiled DLL file "dsapilog.dll" to the Domino R5 server's program 
   directory.

2) Edit the server's "Server" document in the "names.nsf" file (a.k.a. the
   NAB db) and fill in the "DSAPI filter file names" field on the "Internet
   Protocols" -> "HTTP" tab with the name of the filter (i.e., "dsapilog.dll").

3) If the HTTP server task is already running, enter the console command 
   "tell http restart" to load the filter. If HTTP is not running, issue a 
   "load http" command to start it. A message will appear on the server console 
   indicating that the filter has been loaded.

4) Repeat steps 1-3 for all Domino servers that will use this filter.


Note: The filter will create a new file in the format xxYYYYMMDD.log in the
Domino data directory for each day it receives requests.

===========================================================================
Compiling the Filter
===========================================================================
The sample filter included here was compiled using Microsoft Visual C++ 6.0 
on Windows NT Workstation 4.0 (SP4), and linked with the R5.0.3 C API Toolkit
libraries. If you wish to make modifications to the filter and recompile, you 
can follow these steps in VC++ for use in a Windows 32-bit environment:

1) Create a new, empty Win32 Dynamic-Link Library project.

2) Add the following files to the project:
	- dsapimod.h (modified DSAPI header file)
	- dsapilog.c (C source file)
	- dsapilog.h (C header file)

3) Specify "NT" as an additional preprocessor symbol.

4) Specify the Notes C API Toolkit "notesapi\include" directory as 
   an additional include directory, and the "notesapi\lib\mswin32" 
   directory as an additional library directory (this is where 
   notes.lib is located). Note: Use the latest version of the
   Notes C API Toolkit--not the C++ Toolkit--available for download
   from www.lotus.com/developers.

5) Specify the Notes C API Toolkit library "notes.lib" as an additional
   library.

6) Compile and link the project.        


===========================================================================
Caveats & Miscellaneous Notes
===========================================================================
1) As indicated in the article, the date for each entry is left out of the 
   log file on purpose to illustrate a point. As there is a cache mechanism in
   place for performance reasons (whereas each entry is logged to an in-memory 
   buffer instead of directly to the log file), an entry from one day may 
   be flushed to the log file of a different day. If you wish to handle this
   differently, you can update the code to either write each entry directly to 
   the log file (i.e, remove the cache), or write the date out to the file 
   along with each entry.

2) There are issues with capturing the "Content-Length" response header in the 
   DSAPI (it will sometimes return garbage characters) and has been purposely 
   omitted from the code.
									     
3) The filter has only been tested on a Domino R5.0.4 server with Windows NT 
   Server 4.0 (SP4) running with relatively light HTTP traffic.

4) The filter has not been tested in conjunction with the Domino for IIS or 
   DOLS filters, or any other third party filters. In a similar vein, it has
   not been tested on servers hosting multiple virtual hosts.

5) As the filter is written for illustrative purposes, extensive error checking
   has been omitted. You may want to consider adding some additional checks in 
   the code before placing it into a production environment.

6) The kFilterRawRequest, kFilterResponse, and kFilterEndRequest events, at the 
   time of this writing, are hidden events. These were exposed accidentally in 
   an earlier release, and, according to Lotus, will be supported again in the 
   future.


===========================================================================
Disclaimer
===========================================================================
This software is provided AS-IS, and comes with no guarantees, expressed or 
implied. The author cannot be held liable for any damage caused by the use 
of this software. In short, USE AT YOUR OWN RISK. 

In addition, no support is provided for this software.