Name:
AccessByFile
Description:
Verify permissions associated with the resource identified by
the current physical path.
Options:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
RequirePermissions | - | Combination of 'x', 'r', 'w' | Permissions required on file | RequirePermissions="x" |
Option | Meaning |
---|---|
r | Resource must be readable |
w | Resource must be writable |
x | Resource must be executable |
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:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
Pi3Expression | + | A Pi3Expression | Pi3Expression to evaulate | Pi3Expression="&dbreplace(response,string,ObjectMap,Scripts)" |
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:
Provide basic authentication.
Options:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
Realm | + | A string | Realm to authenticate | Realm="Admin" |
Base64 | + | A base64 encoded string | Encoding of username and password | Base64="anJveTpoZWxsbw==" |
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:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
IOObject | - | <A Pi3 Object> | Prototype IO object for proxy forwarding | IOObject "TCPIPClient" |
CacheRoot | - | <directory path> | Relative or Absolute path to cache root | CacheRoot "Cache" |
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.
Options:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
FileIOObject | + | <objectname> | A Pi3 IO object | FileIOObject "CGIFileIO" |
CommandLineByExt | - | <key>="<Pi3Expression>" | A key-value pair with an extension and a Pi3Expression | CommandLineByExt .cgi="perl %p%q" |
DefaultCommandLine | - | <Pi3Expression> | A Pi3Expression, which expands to a command line | DefaultCommandLine "%p %d" |
IncludeParentsEnvironment | Yes | Yes|No | Indicates if parents environment is inherited to CGI children | IncludeParentsEnvironment Yes |
EnvironmentSize | 4096 | <A number> | The number of bytes used for the environment block of CGI children | EnvironmentSize 8192 |
Variable | - | <Pi3Expression> | A variable definition | Variable "GATEWAY_INTERFACE=CGI/1.1" |
ExtraHeaders | Yes | Yes|No | Indicates if extra headers are considered | ExtraHeaders Yes |
ExtraHeadersPrefix | - | <A string> | Used as prefix of each extra header | ExtraHeadersPrefix "HTTP_" |
ExtraHeadersIgnore | - | <Space delimited Strings> | List of unconsidered extra headers | ExtraHeadersIgnore "Content-Type Content-Length" |
KillAfter | -1 | <A number> | Time to wait before killing the process. | KillAfter "-1" |
SendCRLF | No | Yes|No | Adds additional "CRLF" to the CGI input. | SendCRLF Yes |
Flag | - | "16-Bit", etc. | A flag to effect CGI | Flag "16-Bit" |
Flags are:-
16-Bit Windows NT only, expect CGI programs to be 16-Bit
Windows or MS-DOS images, change semantics appropriately.
Parameters:
The Pi3Expressions in the configuration variables DefaultCommandLine,
CommandLineByExt and Variable may contain besides the standard shortcuts
used in Pi3Expressions the following, context specific parameters.
Parameter | Evaluates to |
---|---|
%p | Full pathname to CGI program |
%q | Value of an "isIndex" query |
Example:
<Object> Name CGI Class CGIClass FileIOObject "CGIFileIO" DefaultCommandLine "%p%q" CommandLineByExt .cmd="cmd.exe /c %p%q" CommandLineByExt .pl="perl %p%q" IncludeParentsEnvironment Yes EnvironmentSize 8192 Variable "CONTENT_LENGTH=$Y" Variable "CONTENT_TYPE=$C" Variable "GATEWAY_INTERFACE=CGI/1.1" Variable "PATH_INFO=$I" Variable "PATH_TRANSLATED=$Z" Variable "QUERY_STRING=$q" ExtraHeaders Yes ExtraHeadersPrefix "HTTP_" ExtraHeadersIgnore "Content-Type Content-Length" SendCRLF Yes KillAfter 60 </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:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
SetType | + | A MIME type/subtype pair | Internal directory MIME type | SetType="internal/x-directory" |
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:
Options:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
Flag | - | RefreshOlderThanServer | Force refresh on server start | Flag="RefreshOlderThanServer" |
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:
DigestAuth
Description:
Digest access authentication authentication accordingly to RFC 2069.
Options:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
Realm | + | A string | Realm to authenticate | Realm="Admin" |
User | + | <user-name:hashed-password> | User record | User="holger:bc9b46aaf9b2351ceb9875148d93fda5" |
NonceTimeout | + | A number, 0 for no timeout | Timeout for authentication | NonceTimeout=3600 |
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 DgstAuth Class DgstAuthClass </Object> <Object> ... Handle DgstAuth ... </Object>
:
Name:
DirectoryExists
Description:
Executes the following steps:
Options:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
IndexFile | - | Filename | Index file name | IndexFile="index.html" |
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. HTML directory indexes are
optional sortable and can tag files, which are newer than a threshold
date.
The directory listing sent to the user is composed of the following
document in order
Options:
Option | Default | Values | Short Description | Example(s) | |||||
---|---|---|---|---|---|---|---|---|---|
HeaderPattern | - | A Pi3Expression | Output first | HeaderPattern=" | |||||
HeaderFile | - | A filename | File sent before listing | HeaderFile="HEADER" | |||||
FooterFile | - | A filename | File send after listing | FooterFile="FOOTER" | |||||
ListTop | - | A Pi3Expression | Output before file iteration | ListTop="Directory listing of %p" | |||||
FilePattern | + | A Pi3Expression | Determines output generated for every file | FilePattern="&abbrev(%n,32,...)&align(%s,10,right)" | |||||
ListBottom | - | A Pi3Expression | Output after file iteration | ListBottom=" " | |||||
FooterPattern | - | A Pi3Expression | Output last | FooterPattern="" | |||||
DescriptionFile | - | <filename> | File with descriptions of files | DescriptionFile=".desc" | |||||
MIMEIcon | - | "MIME icon_relative_path" | Maps a MIME specification to an icons path | MIMEIcon="text/* /icons/text.gif"; MIMEIcon="* /icons/unknown.gif" | |||||
Include | - | Regular expression | A file pattern to include | Include="*" | |||||
Exclude | - | Regular expression | A file pattern to exclude | Exclude="." | |||||
HTTPEquiv | - | <rfc822-variable>: <content> | An rfc822 response header to send | HTTPEquiv="Content-Type: text/plain" | |||||
LastModifiedFormat | - | "%a %b %d %Y %T GMT" | Format for file last modified date | LastModifedFormat="%a %b %d %Y %T GMT" | |||||
SwapFileName | - | "file1 file2" | Replace any file1 name with file2 | SwapFileName=".. Parent Directory" | |||||
NewPattern | - | A wellformed HTML fragment | Replaces the %m parameter | NewPattern "<IMG SRC="/icons/new.gif">" | |||||
NewThreshold | - | Threshold for new files in days
| NewThreshold 365
| Options
| -
| Options flags as described below
| Options which effect behaviour
| Options "Name | AltName | Size etc."
| |
the following parameters specific to directory indexing:
Pi3Expression parameter | Evaluates to |
---|---|
%a | Alternate file name |
%b | Empty if file is not a directory |
%c | Media (MIME) type |
%d | Description of the file if available |
%l | File last modified date |
%m | Mark file conditional as new |
%n | File/directory name |
%i | Icon |
%p | Directory (virtual path) |
%r | Relative path |
%s | Size in decimal |
%S | Size of all regular files in decimal |
%N | Number of all files and directories |
filename|its descriptionWhitespace will not be stripped out of the filename or description. Typically this file would also be excluded from the directory list by naming it in an 'Exclude' directive. If present a files description can be accessed via parameter %d.
Option | Meaning |
---|---|
Name | Lookup the name of the file or directory and put it in parameter %n |
AltName | Lookup the alternate name of the file or directory and put it in parameter %a. |
Icon | Evaluate the appropriate icon file for the file based on its extension and MIME type and make it available through parameter %i |
MIMEType | Record the MIME type of the current file in parameter %c. |
RelPath | Record the relative path (path component of URL) to the file in parameter %r. |
Size | Record the filesize of the current file in parameter %s in full decimal. If the current file is a directory '-' is placed in %s. If more than one of 'Size', 'AbbrevSize' or 'FormatSize' are used the results are undefined. |
AbbrevSize | The filesize is abbreviated and placed in parameter %s. The abbreviated file size has the following form '<1K', '3M', '2K', etc. If more than one of 'Size', 'AbbrevSize' or 'FormatSize' are used the results are undefined. |
FormatSize | The filesize is formatted with the comma (',') character seperating thousands. The formatted size of place in parameter $s. If more than one of 'Size', 'AbbrevSize' or 'FormatSize' are used the results are undefined. |
SortDesc | The sort order is alphabetical descending. If this option is omitted the sort order is ascending by default. |
SortCase | The sort order is case sensitive. If this option is omitted the sort order is case insensitive by default. |
SortType | The sort order is determined by the file extension. Directories are on the top of the sort order. |
SortName | The sort order is determined by the name of the file or directory. |
SortSize | The sort order is determined by the filesize. |
SortDate | The sort order is determined by the file date. |
SortDscr | The sort order is determined by the annotations in the DescriptionFile. |
TagNew | All all files newer than NewThreshold are marked with NewPattern. |
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.
Note:
A sorted HTML directory indes is made by using the above sort options and
hyperlinks with special URL parameters within the table headers
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:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
File | + | <filepath> | Relative or Absolute path to log file | File="Logs/access.txt" |
Expression | + | <Pi3Expression> | Pi3Expression to write | Expression="$A $h - [$t] $r $s $b" |
OpenMode | w | w or a | File mode to open logfile with | OpenMode="a" |
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:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
Condition | - | A Pi3Expression | Makes handler conditional | Condition="&cmp(dblookup(response,string,ObjectMap),Scripts)" |
Handlers | - | An optional condition followed by a list of handler names | Handles invoked for all phases | Handlers "yes" "Errors Scripts Default" |
<phase> | - | A phase name followed by an optional condition and a handler | Define a handler for a phase | Destroy "¬($d)" DeleteTemporaryFiles |
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:
ImageMap
Description:
Handle server-side image maps, this version only supports circles,
rectangles and defaults.
Phase:
HANDLE
Returns:
PIAPI_COMPLETED
Note:
Example:
<Object> Name ImageMap Class ImageMapClass </Object> <Object> ... Handle ImageMap ... </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:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
IgnoreStatus | - | 0, 200, etc. | HTTP response codes | IgnoreStatus="0 200" |
<nnn> | - | /errors/404.html, /msgs/403.shtml, etc. | Response specific virtual error paths | 404="/errors/404.html"; 403="/errors/403.shtml" |
DefaultMessage | + | /errors/Unknown.html, /msgs/unknown.shtml, etc. | Default error message virtual path | DefaultMessage="/errors/Unknown.html" |
Action | - | A Pi3Expression | Evaluated if the error code is mapped | Action="&dbreplace(response,sting,ObjectMap,...)" |
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> ... Mapping MapToErrorDocument DefaultMessage="/errors/Unknown.html" 403="/errors/Forbidden.html" ... </Object>
:
Name:
NtlmAuth
Description:
Provide NTLM (challenge response) authentication. Use with Win32 only.
Options:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
Realm | + | A string | Realm to authenticate | Realm="Admin" |
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 NtlmAuth Class NtlmAuthClass </Object> <Object> ... Handle NtlmAuth ... </Object>
:
Name:
PathMapper
Description:
Maps a virtual path to another virtual path or a physical path.
Options:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
From | + | <path> | Search path | From="/" |
To | + | <path> | Replace path | To="/home/WWWDocs/" |
CaseSensitive | Yes | Yes|No | Specifies case sensitivity of "From" matching | CaseSensitive="No" |
PathInfo | No | Yes|No | Specifies if path after "To" is PATH_INFO | PathInfo="Yes" |
Redirect | No | Yes|No | Specifies if path after "To" is a URL for redirection | Redirect="Yes" |
Action | - | A Pi3 Expression | Expression to be evaluated if path is mapped | Action="&dbreplace(response,string,ObjectMap,Scripts)" |
Typically CGI mapping sets PATH_INFO whereas regular document mapping does not.
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:
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:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
RefuseStatus | - | HTTP Response code | Response code to set on failure | RefuseStatus=404; RefuseStatus="403" |
AllowFileMask | - | Combination of 'E', 'F', 'L', 'D' | Logical OR of condition to check | AllowFileMask="EF"; AllowFileMask="EFD" |
Option flag | Meaning |
---|---|
E | Resource must exist |
F | Resource is a regular file |
D | Resource is a directory |
L | Resource is a symbolic link |
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:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
ReturnCode | + | COMPLETED, CONTINUE, REDIRECT, ERROR, ABORT | Specify a handler return code | ReturnCode="COMPLETED" |
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:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
IgnoreStatus | - | 0, 200, etc. | HTTP response codes | IgnoreStatus="0 200" |
<nnn> | - | Fragments/404.html, msgs/403.html, etc. | Response specific error messages | 404="Fragments/404.html"; 403="msgs/403.html" |
DefaultMessage | + | Fragments/Unknown.html, mgs/unknown.html, etc. | Default error message | DefaultMessage="Framents/Unknown.html" |
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. This handler also handles
'PUT', 'DELETE' and 'POST' (HTTP form upload) requests.
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
HeaderPattern | - | A Pi3Expression | Output first | HeaderPattern=" |
FooterPattern | - | A Pi3Expression | Output last | FooterPattern="" |
Methods | GET | HEAD | GET | HEAD | PUT | DELETE | POST | OPTIONS | TRACE | Supported HTTP methods | Methods GET | HEAD | PUT | DELETE |
FileKey | - | A string | Key for the filename part of multipart HTTP message | FileKey "upfile" |
NoteKey | - | A string | Key for the annotation part of a multipart HTTP message | NoteKey "notes" |
UploadPath | - | A valid path in URL format. | Override the default path of a form upload | UploadPath "/uploads/" |
UploadLimit | 0 | A number >= 0. | Limitation of the upload filesize | UploadLimit 2.097.152 |
DescriptionFile | - | A filename without a path | File with annotations about the uploaded file | DescriptionFile ".desc" |
Annotation | - | A Pi3Expression | Expression is written to 'filename_ext.txt' during upload | Annotation "From:\t$A$MHost:\t$h$MTime:\t$t$MUrl:\t\"$r\"$M" |
ChunkLimit | 0 | A number >= 0. | Minimum filesize for chunked transfer-encoding | ChunkLimit 32768 |
Ranges | 'none' | A string, either 'none' or 'bytes'. | Whether or not ranges are allowed. | Ranges bytes |
The action caused by the HTTP methods are
Method | Action |
---|---|
GET | To send the requested file to the browser. |
HEAD | To send only the HTTP header for the requested file to the browser. |
PUT | HTTP/1.1 request, to upload the requested file from a web browser to the server. If the file already exists it must be a writeable and a regular file. |
DELETE | HTTP/1.1 request, to delete the requested file. File must exist and be a regular file or directory. Deletion works not recursive in directories and directory must be empty. |
POST | To upload a file using HTTP form upload with multipart message. An upload form
looks like
|
OPTIONS | HTTP/1.1 request, to retrieve the supported methods for the respective URL or the server itself. |
TRACE | HTTP/1.1 request, which works like an echo handler. this could be used to test the client |
Phase:
HANDLE
Returns:
PIAPI_COMPLETED if the file was sent. INT_REDIRECT is returned in a POST
request if the file was uploaded.
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:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
Pi3Expression | + | A Pi3Expression | Pi3Expression to be sent | "Process [$P], Thread [$k]" |
InMultipartResponse | No | Yes, No | Multipart response indicator | InMultipartResponse=Yes |
BufferSize | -1 | A decimal number | Maximum message length | BufferSize=4096 |
HTTPEquiv | - | "<rfc822_variable>: <content>" | HTTP Entity header | "Content-Type: text/html" |
response in the following way:
The values 'Yes' or 'No' (not case sensitive) may be used.
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:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
Exec | No | 'Yes' or 'No' | Specific whether CGI scripts may be executed | Exec="Yes" |
HeaderPattern | - | A Pi3Expression | Output first before the page | HeaderPattern=" |
FooterPattern | - | A Pi3Expression | Output last | FooterPattern="" |
ExecFileFixup | - | A Pi3Expression | Evaluated to fixup CGI markers | ExecFileFixup="&dbreplace(response,string,ObjectMap,Scripts)" |
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:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
StatusCode | + | An HTTP response code in 3 digital decimal form | Specify an HTTP reponse code to be set | StatusCode="403" |
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:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
VirtualHostObject | + | <objectname> | VirtualHost object to associate | VirtualHostObject="vhost1" |
BindAddress | + | IP address of form www.xxx.yyy.zzz | Server bound IP address | BindAddress="172.23.23.37" |
BindAddressVariable | "LocalAddr" | Variable name | IO object variable name | BindAddressVariable="LocalAddr" |
Phase:
HOSTMAP
Example:
<Object> Name VirtualHostByAddress Class VirtualHostByAddressClass BindAddressVariable "LocalAddr" </Object> <Object> ... HostMap VirtualHostByAddress VirtualHostObject="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:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
VirtualHostObject | + | <objectname> | VirtualHost object to associate | VirtualHostObject="vhost1" |
HostName | + | A hostname | Hostname of virtual host. | Hostname="foo.name.dom" |
Phase:
HOSTMAP
Example:
<Object> Name VirtualHostByName Class VirtualHostByNameClass </Object> <Object> ... HostMap VirtualHostByName VirtualHostObject="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:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
VirtualHostObject | + | <objectname> | VirtualHost object to associate | VirtualHostObject="vhost1" |
URLPath | + | A URL Path fragment | The URL path to use | URLPath="/vhost1/" |
Phase:
HOSTMAP
Example:
<Object> Name VirtualHostByURL Class VirtualHostByURLClass BindAddressVariable "LocalAddr" </Object> <Object> ... HostMap VirtualHostByURL VirtualHostObject="host1.foo.dom" \ URLPath="/host1/" ... </Object>
:
Name:
WinCGI
Description:
This HTTP Handler handles WinCGI requests.
Options:
Option | Default | Values | Short Description | Example(s) |
---|---|---|---|---|
FileIOObject | + | <objectname> | A Pi3 IO object | FileIOObject "CGIFileIO" |
CommandLineByExt | - | <key>="<Pi3Expression>" | A key-value pair with an extension and a Pi3Expression | CommandLineByExt .cgi="perl %p%q" |
DefaultCommandLine | - | <Pi3Expression> | A Pi3Expression, which expands to a command line | DefaultCommandLine "%p %d" |
ExtraHeaders | Yes | Yes|No | Indicates if extra headers are considered | ExtraHeaders Yes |
ExtraHeadersPrefix | - | <A string> | Used as prefix of each extra header | ExtraHeadersPrefix "HTTP_" |
ExtraHeadersIgnore | - | <Space delimited strings> | List of unconsidered extra headers | ExtraHeadersIgnore "Content-Type Content-Length" |
ExternalPath | - | <Pi3Expression> | Path to external CGI form data files | ExternalPath "./CGITemp/" |
DataFile | - | <Pi3Expression> | Path to CGI data file | DataFile "./CGITemp/%u.ini" |
StdinFile | - | <Pi3Expression> | Path to CGI input file | StdinFile "./CGITemp/%u.in" |
StdoutFile | - | <Pi3Expression> | Path to CGI output file | StdoutFile "./CGITemp/%u.out" |
DataBlock | - | <Pi3Expression> | Block of text written to datafile | DataBlock "[CGI]\nRequest Protocol..." |
KillAfter | -1 | <A number> | Time to wait before killing the process. | KillAfter "-1" |
SendCRLF | No | Yes|No | Adds additional "CRLF" to the CGI input. | SendCRLF Yes |
Flag | - | "16-Bit", etc. | A flag to effect CGI | Flag "16-Bit" |
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.
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.
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.
This mechanism is typically used to support CGI variants other than standard CGI, namely WinCGI and DOSCGI.
Flags are:-
16-Bit Windows NT only, expect CGI programs to be 16-Bit
Windows or MS-DOS images, change semantics appropriately.
Parameters:
The Pi3Expressions in the configuration variables DataFile, StdinFile,
StdoutFile and DataBlock may contain besides the standard shortcuts
used in Pi3Expressions the following, context specific parameters.
Parameter | Evaluates to |
---|---|
%d | Full pathname to the data file |
%i | Full pathname to the content file |
%o | Full pathname of the output file |
%p | Full pathname to WinCGI program |
%u | Unique ID in the context of the current process (PID) |
%q | Value of an "isIndex" query |
%h | List of extra request headers in Windows ini-format |
%a | List of accepts headers in Windows ini-format |
%l | List of decoded form literals in Windows ini-format |
%e | List of decoded external form literals in Windows ini-format |
%g | List of encoded huge form data in Windows ini-format |
%f | List of uploaded multipart/form-data files in Windows ini-format |
Example:
<Object> Name MyWinCGI Class WinCGIClass FileIOObject "CGIFileIO" CommandLineByExt .cgi="perl %p %d" DefaultCommandLine "%p %d" ExtraHeaders Yes ExtraHeadersPrefix "HTTP_" ExtraHeadersIgnore "Content-Type Content-Length" ExternalPath "cgi-temp/" DataFile "cgi-temp/$P_%u.dat" StdinFile "cgi-temp/$P_%u.in" StdoutFile "cgi-temp/$P_%u.out" DataBlock "\[CGI]$M\ Request Protocol=$H$M\ Request Method=$m$M\ $M\ [Accept]$M\ %a$M\ [System]$M\ Output File=%o$M\ Content File=%i$M\ $M\ [Extra Headers]$M\ %h$M\ [Form Literal]$M\ %l$M\ [Form External]$M\ %e$M\ [Form File]$M\ %f$M\ [Form Huge]$M\ %g$M" </Object>