Name:
AccessByFile

Description:
Verify permissions associated with the resource identified by the current physical path.

Options:

Overview

Description of Options

RequirePermissions

Phase:
CHECKACCESS

Returns:
PIAPI_ERROR if this handler was invoked for an inappropriate phase, otherwise PIAPI_COMPLETED is returned. If the resource does not have the required permissions this handler sets the response status to 403 Forbidden.

Note:
Not all permission flags may be checked on all operating systems, where a permission cannot be verified because the operating system does not support the flag that permission will be considered passed. An observation of this note is that a later phase may fail to access a resource that passed this verification for the access attempted.

Example:

	<Object>
		Name AccessByFile
		Class AccessByFileClass
	</Object>

	<Object>
		...
		CheckAccess AccessByFile RequirePermissions="R"
		...
	</Object>

	

:

Name:
Action

Description:
Evaluate a Pi3Expression to cause a side effect.

Options:

Overview

Description of Options

Pi3Expression

Phase:
Any

Returns:
PIAPI_ERROR if this handler was invoked for an inappropriate phase, otherwise PIAPI_CONTINUE is returned.

Example:

	<Object>
		Name Action
		Class ActionClass
	</Object>

	<Object>
		...
		CheckType Action Pi3Expression="&dbreplace(response,rfc822,\
			Content-Type,text/plain)"
		...
	</Object>

	

:

Name:
BasicAuth

Description:
Basic authentication is not included in this distribution.

Options:

Overview

Description of Options

Base64

Realm

Phase:
CHECKAUTH

Returns:
PIAPI_COMPLETED if authentication passed. INT_REDIRECT if the status was set to 401 to challenge, PIAPI_CONTINUE if this handler choose to take no action and PIAPI_ERROR if this handler was invoked for a phase other than CHECKAUTH.

Note:

Example:

	<Object>
		Name BasicAuth
		Class BasicAuthClass
	</Object>

	<Object>
		...
		Handle BasicAuth 
		...
	</Object>
	

:

Name:
BasicProxy

Description:
Perform simple proxy requests. This handler allows some filtering of forward client headers, but no caching. Proxy requests use HTTP/1.0

Options:

Overview

Description of Options

IOObject

CacheRoot

Phase:
HANDLE

Returns:
PIAPI_COMPLETED on success. If this handler was invoked for a phase other than HANDLE then PIAPI_ERROR is returned.

Note:

Example:

	<Object>
		Name BasicProxy
		Class BasicProxyClass
	</Object>

	<Object>
		...
		Handle BasicProxy
		...
	</Object>

	

:

Name:
CGI

Description:
This HTTP Handler handles CGI requests. This documentation is not completed. Please refer to source file and/or example configuration files for typical usage.

Options:

Overview

Description of Options

FileIOObject

Variable

DataFile

This mechanism is typically used to support CGI variants other than standard CGI, namely WinCGI and DOSCGI.

Specification of 'DataFile', 'StdinFile' or 'StdoutFile' cause the standard CGI streams environment to be disabled.

StdinFile

This mechanism is typically used to support CGI variants other than standard CGI, namely WinCGI and DOSCGI.

Specification of 'DataFile', 'StdinFile' or 'StdoutFile' cause the standard CGI streams environment to be disabled.

StdoutFile

This mechanism is typically used to support CGI variants other than standard CGI, namely WinCGI and DOSCGI.

Specification of 'DataFile', 'StdinFile' or 'StdoutFile' cause the standard CGI streams environment to be disabled.

DataBlock

This mechanism is typically used to support CGI variants other than standard CGI, namely WinCGI and DOSCGI.

KillAfter

Flag

Flags are:-
16-Bit Windows NT onlyExpect CGI programs to be 16-Bit Windows or MS-DOS images, change semantics appropriately.

Example:

	<Object>
		Name CGI
		Class CGIClass
		FileIOObject "CGIFileIO"
		Variable "GATEWAY_INTERFACE=CGI/1.1"
	</Object>

	<Object>
		Name CGI
		Class CGIClass
		FileIOObject "CGIFileIO"
		Variable "GATEWAY_INTERFACE=WinCGI/1.0"
		CGITempDir "CGITemp"
		DataFile "./CGITemp/%u.dat"
		StdinFile "./CGITemp/%u.in"
		StdoutFile "./CGITemp/%u.out"
		DataBlock "[CGI]\nRequest Protocol=HTTP/1.0\n"
	</Object>
	

:

Name:
CheckForDirectory

Description:
Check if the resources identified by the physical path is a directory. If the resource is a directory then set the Content-Type of the resource to the type identified by the 'SetType' parameter.

Options:

Overview

Description of Options

SetType

Phase:
CHECKTYPE

Returns:
PIAPI_COMPLETED if the resource was a directory and the Content-Type was set to the type specified by the 'SetType' parameter.

Example:

	<Object>
		Name CheckForDirectory
		Class CheckForDirectoryClass
	</Object>

	<Object>
		...
		CheckType CheckForDirectory SetType="internal/x-directory"
		...
	</Object>

	

:

Name:
ConditionalGet

Description:
Set the HTTP response status code to '304 Not Modified' if all the

following criteria are met:

• The HTTP request method is 'GET'.
• The HTTP request contains an 'If-Modified-Since' client header.
• The resource is older than the date specified by the 'If-Modified-Since' header.

Options:

Overview

Description of Options

Flag

RefreshOlderThanServer forces the handler not to return 304 (not modified) status for a file modified before the server was last restarted (this handler was loaded).

Phase:
Any phase, usually CHECKPATH.

Returns:
PIAPI_COMPLETED if the status was set to '304 Not Modified', otherwise PIAPI_CONTINUE.

Example:

	<Object>
		Name ConditionalGet
		Class ConditionalGetClass
	</Object>

	<Object>
		...
		CheckType ConditionalGet
		...
	</Object>

	

:

Name:
DeleteTemporaryFiles

Description:
Deletes temporary files from a response cycle. Temporary files are listed in the "TemporaryFile", string variable of the response DB.

If debugging is enabled this handler will not delete any files.

Phase:
DESTROY

Returns:
PIAPI_CONTINUE, or PIAPI_ERROR if invoked for a phase other than DESTROY.

Note:

Example:

	<Object>
		Name DeleteTemporaryFiles
		Class DeleteTemporaryFilesClass
	</Object>

	<Object>
		...
		Destroy DeleteTemporaryFiles
		...
	</Object>

	

:

Name:
DirectoryExists

Description:

Executes the following steps:

• If the physical path does not have a trailing '/' character then cause a '301 Permanent Redirect' response to the client with the corrected URL. This correctative action avoids some problems with directory indexing.
• If the directory contains one of the files specified by the 'IndexFile' parameter then cause an internal redirect to that file.

Options:

Overview

Description of Options

IndexFile

Phase:
CHECKPATH

Returns:
PIAPI_COMPLETED if the phase completed succesfully. PIAPI_CONTINUE if no action was taken, this will occur when the specified resource is not a directory. PIAPI_ERROR and PIAPI_ABORT respectively when generic and severe errors occur.

Example:

	<Object>
		Name DirectoryExists
		Class DirectoryExistsClass
	</Object>

	<Object>
		...
		CheckPath DirectoryExists IndexFile="index.html" \
			IndexFile="default.html"
		...
	</Object>

	

:

Name:
DirectoryIndex

Description:
Generate directory indexes based on flexible criteria and send the output directly to the remote client. The directory listing sent to the user is composed of the following

document in order:
An optional header, specified by 'HeaderPattern'. An optional header file from the directory, specified by 'HeaderFile'. An optional list start pattern, specified by 'ListTop'. Every applicable file in the directory, output format is specified by 'FilePattern'. An optional list end pattern, specified by 'ListBottom'. An optional footer file, specified by 'FooterFile'. An optional footer pattern, specified by 'FooterPattern'.

Options:

Overview

Description of Options

HeaderPattern

FooterPattern

HeaderFile

FooterFile

ListTop

FilePattern

the following parameters specific to directory indexing:

ListBottom

MIMEIcon

DescriptionFile

file is of the form:

	filename|its description

Include

Exclude

LastModifiedFormat

HTTPEquiv

SwapFileName

Options

Phase:
HANDLE

Returns:
PIAPI_COMPLETED if a directory index was succesfully sent to the client. PIAPI_CONTINUE if this handler done nothing. PIAPI_ERROR and PIAPI_ABORT on generic and severe error conditions.

Example:

	<Object>
		Name DirectoryIndex
		Class DirectoryIndexClass
		Options "Name | Size | MIMEType"
	</Object>

	<Object>
		...
		Handle DirectoryIndex 
		...
	</Object>
	

:

Name:
ExpressionLogger

Description:
Writes a logfile with flexible data and format.

Options:

Overview

Description of Options

File

Expression

OpenMode

Phase:
LOG

Returns:
PIAPI_ERROR if this handler was invoked for a phase other than LOG. Otherwise PIAPI_CONTINUE;

Example:

	<Object>
		Name ExpressionLogger
		Class ExpressionLoggerClass
		OpenMode "a"
		Expression "$A $h - [$t] $r $s $b"
	</Object>

	<Object>
		...
		Log ExpressionLogger File="Logs/access.txt"
		...
	</Object>

	

:

Name:
FlexibleHandler

Description:
Dispatches requests to multiple handlers depending on the request phase.

Options:

Overview

Description of Options

Condition

Handlers

<phase>

Phase:
All

Returns:
PIAPI_COMPLETED if the request from processed, PIAPI_CONTINUE otherwise. PIAPI_ERROR or PIAPI_ABORT if any sub-handler returned these error codes.

Example:

	<Object>
		Name FlexibleHandler
		Class FlexibleHandlerClass
		Condition "&cmp(dblookup(response,string,ObjectMap),Scripts)"
		Handlers Condition="<expr>" "Errors Scripts Default"
		Init ...
		Headers ...
		HostMap ...
		Mapping ...
		CheckPath ...
		CheckAccess ...
		CheckType ...
		Handle ...
		Handle Condition="<expr>" ...
		Handle ...
		Log Condition="<expr>" ...
		Destroy Condition="<expr>" ...
	</Object>

	<Object>
		...
		Handle FlexibleHandler 
		...
	</Object>

	

:

Name:
MIMETypeByExtension

Description:
Set the MIME Type of the resource identified by the current physical path by using the function HTTPCore_getMIMETypeFromExtension().

This looks up the MIME type using the file extension component of the physical path in the list of MIME types loaded into the server.

Phase:
CHECKTYPE

Returns:
PIAPI_CONTINUE in all cases.

Example:

	<Object>
		Name MIMETypeByExtension
		Class MIMETypeByExtensionClass
	</Object>

	<Object>
		...
		CheckType MIMETypeByExtension
		...
	</Object>
	

:

Name:
MapToErrorDocument

Description:
This handler sets an error document virtual path according to the HTTP error status code. Subsequent mapping handlers map this virtual path to a physical path. If a virtual path is mapped a number of the original client RFC822 request headers are modified or removed, most notably, the Method is set to 'GET' and any 'If-Modified-Since' headers are removed. This avoids confusion where subsequent handlers interpret the error resource in the context of meta information of the original resource.

Options:

Overview

Description of Options

IgnoreStatus

<nnn>

DefaultMessage

Action

Phase:
MAPPING

Returns:
PIAPI_CONTINUE in all non-error cases, whether or not an error virtual path was set. PIAPI_ERROR and PIAPI_ABORT respectively for generic and severe error conditions.

Example:

	<Object>
		Name MapToErrorDocument
		Class MapToErrorDocumentClass
		IgnoreStatus "0 200"
	</Object>

	<Object>
		...
		Handle MapToErrorDocument DefaultMessage="/errors/Unknown.html" 403="/errors/Forbidden.html"
		...
	</Object>

	

:

Name:
PathMapper

Description:
Maps a virtual path to another virtual path or a physical path.

Options:

Overview

Description of Options

From

To

CaseSensitive

PathInfo

Typically CGI mapping sets PATH_INFO whereas regular document mapping does not.

Action

Phase:
MAPPING

Returns:
PIAPI_ERROR if this handler was invoked for an inappropriate phase, otherwise, PIAPI_COMPLETED if a path was mapped and PIAPI_CONTINUE if no path was mapped.

Note:
The 'From' pattern must begin and end with '/' character, otherwise an initialization error will be raised. This is to ensure that path mapping does not result in unintended files becoming visible.

Note that paths are mapped in the order listed in the configuration file, so a path mapping statement with From="/" would match before one with From="/icons/" is listed first. Path mapping should be list in reverse order of directory depth to ensure correct mapping (place mapper with From="/" AFTER the one with From="/icons/").

Example:

	<Object>
		Name PathMapper
		Class PathMapperClass
	</Object>

	<Object>
		...
		CheckAccess PathMapper From="/" To="/home/Pi3Web/WebRoot/"
		...
	</Object>

	

:

Name:
ReadRequestHeaders

Description:
Read the status line and client request headers for a new HTTP client request. On read a correct request this handler may disable connection keep open for the request if it is enable and any of the following conditions are

met:

• The client protocol is HTTP/1.0 and the 'Connection: Keep-Alive' header variable-value pair does not exist.
• The client protocol is HTTP/1.1 and the 'Connection: Close' header variable-value pair exists.

Phase:
HEADERS

Returns:
PIAPI_COMPLETED if the phase completed without serious error. An HTTP error status response (such as '400 Bad Request') may have been set. On error PIAPI_ERROR is returned. An example of an error would be invoking this handler for a phase other that 'HEADERS'.

Example:

	<Object>
		Name ReadRequestHeaders
		Class ReadRequestHeadersClass
	</Object>

	<Object>
		...
		Headers ReadRequestHeaders
		...
	</Object>

	

:

Name:
RefuseFileByMask

Description:
Set an HTTP error response code if the physical resource does not match particular criteria.

Options:

Overview

Description of Options

RefuseStatus

AllowFileMask

Phase:
CHECKPATH

Returns:
INT_REDIRECT (via HTTPUtil_doHTTPError()) to cause the HTTP error specified by RefuseStatus to occur if the conditions specified by AllowFileMask are not met. Otherwise PIAPI_CONTINUE is returned to allow other path checking handlers to be invoked. PIAPI_ERROR is returned if this handler is used to respond to a phase other than 'CHECKPATH'.

Example:

	<Object>
		Name RefuseFileByMask
		Class RefuseFileByMaskClass
	</Object>

	<Object>
		...
		CheckPath RefuseFileByMask AllowFileMask="EF" RefuseStatus=404
		...
	</Object>

	

:

Name:
ReturnCode

Description:
Returns the specified error code. This handler can be used to 'fake' a response to a phase, or to otherwise cause the specified return code to be given.

Options:

Overview

Description of Options

ReturnCode

Phase:
Any

Returns:
The specified return code.

Note:

Example:

	<Object>
		Name ReturnCode
		Class ReturnCodeClass
	</Object>

	<Object>
		...
		CheckAuth ReturnCode ReturnCode="COMPLETED"
		...
	</Object>

	

:

Name:
SendErrorMessage

Description:
This handler object sends specific canned error message text for each HTTP error status code.

Options:

Overview

Description of Options

IgnoreStatus

<nnn>

DefaultMessage

Phase:
HANDLE

Returns:
PIAPI_COMPLETED on success. PIAPI_CONTINUE if no action taken. PIAPI_ERROR and PIAPI_ABORT respectively for generic and severe error conditions.

Example:

	<Object>
		Name SendErrorMessage
		Class SendErrorMessageClass
		IgnoreStatus "0 200"
	</Object>

	<Object>
		...
		Handle SendErrorMessage DefaultMessage="Fragments\Unknown.html" 403="Fragments\Forbidden.html"
		...
	</Object>
	

:

Name:
SendFile

Description:
Send a file including headers to a remote client. If this is a 'HEAD' request only the HTTP headers will be sent. HeaderPattern - A Pi3Expression Output first HeaderPattern="" FooterPattern - A Pi3Expression Output last FooterPattern="" - in the default indicates no default
+ in the default indicates the field is mandatory

Description of Options

HeaderPattern

FooterPattern

Phase:
HANDLE

Returns:
PIAPI_COMPLETED if the file was sent. If this handler was invoked for a phase other than HANDLE then PIAPI_ERROR is returned.

Note:

Example:

	<Object>
		Name SendFile
		Class SendFileClass
	</Object>

	<Object>
		...
		Handle SendFile
		...
	</Object>

	

:

Name:
SendPi3Expression

Description:
This handler object evalulates and sends a Pi3Expression to a the client. By default this handler will send the result in the context of a single-bodied response to the client. This default can be overriden so this handler sends one content-body of a mulipart response.

Options:

Overview

Description of Options

Pi3Expression

InMultipartResponse

response in the following way:
The handler will not return PIAPI_COMPLETED, but PIAPI_CONTINUE, to allow multiple responses to be listed in order for the HANDLE phase. Only the entity headers will be send to the client (Content-Type, Content-Length, etc.) not the general headers (Server, Connection etc.). The seperator header willl be sent as appropriate. The values 'Yes' or 'No' (not case sensitive) may be used.

BufferSize

HTTPEquiv

Phase:
HANDLE

Returns:
PIAPI_COMPLETED on success if InMultiPartResponse is 'No'. PIAPI_CONTINUE if no action taken or on success and InMultiPartResponse is 'Yes'. PIAPI_ERROR and PIAPI_ABORT respectively for generic and severe error conditions.

Example:

	<Object>
		Name SendPi3Expression
		Class SendPi3ExpressionClass
		BufferSize 128
		HTTPEquiv "Content-Type: text/plain"
	</Object>

	<Object>
		...
		Handle SendPi3Expression \
			Pi3Expression="Hello, your computer's hostname is $h."
		...
	</Object>

	

:

Name:
SendSSI

Description:
Parse and send server-side includes.

Options:

Overview

Description of Options

Exec

HeaderPattern

FooterPattern

ExecFileFixup

Note:

Phase:
HANDLE

Returns:
PIAPI_COMPLETED if the file was sent. If this handler was invoked for a phase other than HANDLE then PIAPI_ERROR is returned.

Example:

	<Object>
		Name SendSSI
		Class SendSSIClass
	</Object>

	<Object>
		...
		Handle SendSSI Exec="Yes" 
		...
	</Object>

	

:

Name:
StatusCode

Description:
Cause the given status code to be set for this handler.

Options:

Overview

Description of Options

StatusCode

Phase:
Any

Returns:
PIAPI_COMPLETED.

Note:

Example:

	<Object>
		Name StatusCode
		Class StatusCodeClass
	</Object>

	<Object>
		...
		CheckAccess StatusCode StatusCode="403"
		...
	</Object>

	

:

Name:
VirtualHost

Description:
A virtual host object is a placeholder for variable-value attribute pairs associated with virtual hosts. This object creates its own PIDB and stores parameters in it for reference. A pointer to this PIDB is access by other parts of the HTTP server via the GetHostDB() method of the PIHTTP object.

Options:
Ad hoc options. All parameters are stored in this object PIDB with type PIDBTYPE_RFC822.

Phase:
No phase. It is an error to invoke this object as part of phase handling.

Returns:
PIAPI_ERROR always, because this is not a handler.

Example:

	<Object>
		Name VirtualHost
		Class VirtualHostClass
		HostName "host1"
		Administrator "jroy@johnroy.com"
	</Object>

	

:

Name:
VirtualHostByAddress

Description:
Some operating systems allow multiple IP address to be used by the same computer. On such systems it is possible to have multiple HTTP servers simulated by the same server by customizing the servers behaviour depending on the local IP address to which the client is bound. This handler allows the requests virtual host object to be changed depending on the local IP address of the request.

Options:

Overview

Description of Options

VirtualHostObject

BindAddress

BindAddressVariable

Phase:
HOSTMAP

Example:

	<Object>
		Name VirtualHostByAddress
		Class VirtualHostByAddressClass
		BindAddressVariable "LocalAddr"	
	</Object>

	<Object>
		...
		VirtualHost VirtualHostByAddress VirtualHost="host1.foo.dom" \
			BindAddress=120.0.0.1
		...
	</Object>

	

:

Name:
VirtualHostByName

Description:
This handler allows the virtual host to be changed by filtering the 'Host' rfc822 header field sent by the browser.

Options:

Overview

Description of Options

VirtualHostObject

Hostname

Phase:
HOSTMAP

Example:

	<Object>
		Name VirtualHostByName
		Class VirtualHostByNameClass
		BindAddressVariable "LocalAddr"	
	</Object>

	<Object>
		...
		VirtualHost VirtualHostByName VirtualHost="host1.foo.dom" \
			HostName="host1.foo.dom"
		...
	</Object>

	

:

Name:
VirtualHostByURL

Description:
This handler allows the virtual host to be changed by remaping the the begining of the URL path from the client.

Options:

Overview

Description of Options

VirtualHostObject

URLPath

Phase:
HOSTMAP

Example:

	<Object>
		Name VirtualHostByURL
		Class VirtualHostByURLClass
		BindAddressVariable "LocalAddr"	
	</Object>

	<Object>
		...
		VirtualHost VirtualHostByURL VirtualHost="host1.foo.dom" \
			URLPath="/host1/"
		...
	</Object>