WebSTAR 4 Manual & Technical Reference

Manual Contents | Chapter Contents | Previous Page | Next Page

Developing WebSTAR API Plug-Ins

The WebSTAR Application Program Interface ( API ) is a modular, high-performance technique for developers to extend the functionality of WebSTAR. The WebSTAR API uses CFM on PowerPC systems to implement these Plug-Ins.

Theory of Operation

WebSTAR API Plug-Ins exist as part of the web server's running code, can be called from threads within WebSTAR, and have access to data and services provided to the Plug-In by the web server. Plug-In developers have to take care to cooperate with the web server and other Plug-Ins. Provisions exist for giving Plug-Ins idle CPU time on a regular basis, so you aren't limited to performing all of your processing in the context of a single subroutine call. In addition, Plug-Ins can listen on multiple TCP ports, perform routing of browser requests, return to the server the HTTP response code they sent to the client, and display their own windows.

Complete documentation of the WebSTAR API is included in the WebSTAR API SDK, which is a custom install option in the WebSTAR Server Suite Installer . The SDK can also be found at:

 

ftp://ftp.starnine.com/pub/webstar_dev/wsapi_sdk.sea.hqx

Filter Plug-Ins

All Filter Plug-Ins get called immediately after the server has read the incoming HTTP request and before any processing has begun. They will receive all the request information, and can change it as appropriate. For example, the WebSTAR JRun Servlet Runner checks for the text /servlet/ in a URL and adds the suffix .servlet . This ensures that the WebSTAR Suffix Mapping process will correctly direct requests for Java servlets. Then the filter passes the request back to the server, which may pass it to another filter. For WebSTAR, all Filter Plug-Ins are invoked in reverse alphabetic order (i.e., last to load is first to run). The details are contained in the WebSTAR API documentation.

Filters can only change request text, they can't return results.

There are good reasons to write a filter rather than a Pre-processor: Your filter can work with other filters, while each server can only have one Pre- processor, making filters much more compatible. And filters can automatically install the suffix data in the Suffix Mapping Table, while Pre-processors must be designated by the user.

WebSTAR API Parameter Definitions

This table contains a complete listing of WebSTAR API parameters, keywords and a short description describing the value returned.

While these WebSTAR API parameters are primarily for use by WebSTAR API Plug-In developers, they can also be used in connection with Plug-Ins like WebSTAR SSI which allow WebSTAR API parameter values to be returned from the echo command. For instance:

 

	<!--#echo var="piTotalConnections"-->

In addition, the values of these parameters are accessible by the WSAPI_GetIindexedParameter Apple Event function.

WebSTAR API Parameter Definitions  

Parameter Name

Keyword

Description

Connection-related

 

Read-only values

piPathArgKeyword

----

Path argument portion of URL

piSearchArgKeyword

'kfor'

Search argument portion of URL

piUserKeyword

'user'

Username for current authentication scheme

piPasswordKeyword

'pass'

Password for current authentication scheme

piFromUser

'frmu'

"From" header field (e-mail address when supplied)

piAddressKeyword

'addr'

domain name of client

piPostKeyword

'post'

first 24k of HTTP object body (e.g., form data, etc.)

piMethodKeyword

'meth'

HTTP method (e.g., GET, POST, HEAD, etc.)

piServerName

'svnm'

domain name of server

piServerPort

'svpt'

port number server is listening on

piScriptName

'scnm'

name of CGI or URL path if executing as an action

piContentType

'ctyp'

MIME type of the HTTP object body

piContentLength

'CLen'

data size of the HTTP object body

piRefererKeyword

'refr'

"Referer" HTTP header field value

piUserAgentKeyword

'Agnt'

"User-Agent" HTTP header field value

piActionKeyword

'Kact'

name of action associated with current URL request

piActionPathKeyword

'Kapt'

path to the CGI processing the current URL request

piClientIPAddress

'Kcip'

4 byte integer containing client's IP address

piFullRequestKeyword

'Kfrq'

Entire HTTP request as received from the client

piFileMIMEType

'Mime'

MIME type of requested URL as determined by server

piServerField

'SvFd'

preconstructed response header field for server name

piServerDirectoryPath

'SPth'

local file system path to the server's document tree

piURLPhysicalPath

'UPth'

local file system name for the requested file

piIfModifiedSince

'IfMS'

true/false if file has been modified since last client request

piURLFileRef

'Pufr'

server-specific reference to file in the native OS

piCurrentRealm

'CRlm'

name of security realm (if any) protecting requested file

piConnectionID

'LCID'

unique ID for this HTTP connection

piServerUniqueID

'LSID'

unique ID for this execution of the server

Server Status Info

 

Read-only values

piTotalConnections

'STCn'

total number of connections served since start-up

piCurrentUserLevel

'SCLd'

current number of users connected to the server

piHighestUserLevel

'SMLd'

max number of users ever connected at one time

piCurrentFreeMemory

'SFMm'

current amount of free memory available to the server

piMinimumFreeMemory

'SMFM'

minimum amount of free memory ever available to server

piTotalConTimeouts

'STTm'

total number of connections that have timed out

piTotalConBusies

'STBz'

total number of connections refused because server was busy

piTotalConDenied

'STDn'

total number of connections denied for access violations

piTotalBytesSent

'TByt'

total bytes transmitted to clients

piVersionNumber

'Pvrs'

name and version number of server

piUpSinceDate

'SUpS'

date & time the server was launched in the format MM/DD/YY:HH:MM

piPluginAdminInfo

'Padm'

text block containing info on each Plug-In currently installed

Plug-in Info

 

Read-only values

piPluginParamInfo

'Pipi'

pointer to a WebSTAR API-specific data structure describing Plug-In parameter semantics

piPluginParamCount

'Pipc'

count of the number of WebSTAR API parameters in piPluginParamInfo

piPluginDirPath

'Pdph'

full path to the Plug-Ins folder

piPluginDirFSSpec

'Pdfs'

platform-specific file system reference to Plug-Ins folder

Logging Info

 

Read-only values

piTransferResult

'LTRs'

result of processing URL (OK, ERR!, PRIV)

piBytesSent

'LByt'

bytes sent for current request

piTransferTime

'LTrT'

time in ticks from connection open to close

Special Routing Settings

 

Read/Write access

piIndexFile

'Pixf'

name of file in each directory to return as a default

piErrorFile

'Perf'

relative path to Mac file/CGI handling file not found

piNoAccessFile

'Pnaf'

relative path to file/CGI handling access violations

Global Server Settings

 

Read/Write access

piDumpBufSize

'Dbuf'

chunk size for TCP/IP output

piPigDelay

'PigD'

time in ticks between WaitNextEvent calls

piMaxUsers

'MaxU'

maximum number of simultaneous connections allowed

piNoDNS

'Ndns'

toggle DNS look-ups on/off.

piTimeOut

'TimO'

timeout in seconds for inactive connections

piMaxListens

'MaxL'

same value as Max Users. Should be set to the same value

piLogging

'Plog'

toggle log file output on/off (1/0)

piVerboseMessages

'Pvrb'

toggle server debugging messages on/off (1/0)

piRefuseConnections

'Pcon'

toggle connection refusal on/off (1/0)

piHideWindow

'Phid'

toggle status window hiding on/off (1/0)

piDefaultMIMEType

'Pmim'

default MIME types for files with no suffix mapping

piPort

'Pprt'

port for server to make HTTP connections on

piLogFile

'Plgf'

relative path to server log file

piSuffixMappings

'Psuf'

text block defining suffix mapping info

piAllowDeny

'Pa/d'

text block defining allow/deny IP security

piAllowDenyByRealm

'PADr'

This is an indexed value and you must use the WSAPI_GetIndexedParameter or WSAPI_SetIndexedParameter call to manipulate it. The Index is the name of the realm to get or set allow/deny info for.

piRealms

'Prlm'

text block defining realm security

piActions

'Pact'

text block defining user-defined actions

piLogFormat

'Plfm'

text block defining log file format

piPreProcessor

'Ppre'

relative path to CGI/Plug-In handling preprocessor

piPostProcessor

'Ppst'

relative path to CGI/Plug-In handling postprocessor

piReportDelay

'Prdl'

amount of time in seconds between status report events

piCacheFlush

'Pcfl'

setting this flag indicates the server should flush any cached data

piFileInfoCacheSize

'Pfic'

amount of memory to allocate to file info caching

piKeepAliveConnections

'Pkac'

number of connections per client to keep alive

piKeepAliveTime

'Pkat'

seconds to keep alive idle client connections

piServerCName

'Pscn'

canonical name of server to be used in HTTP responses, regardless of DNS name

piCGIBinOnly

'Pcbo'

flag determining if CGIs will be executed from the /cgi-bin folder only

piServiceAddress

'Pisa'

table of registered service addresses

WebSTAR-specific

 

 

piSSLInterface

 

See starnine.h file in the SDK for details

piBrowserBufferBag

 

See starnine.h file in the SDK for details

piDefaultAction

 

See starnine.h file in the SDK for details

piByteServerAction

 

See starnine.h file in the SDK for details

piCGIPersist

 

See starnine.h file in the SDK for details

piSSLPort

 

See starnine.h file in the SDK for details

piWNEThreshold

 

See starnine.h file in the SDK for details

piSSLAvailable

 

See starnine.h file in the SDK for details

piFragList

 

 

piFagVers

 

 

Error Checking

If the path to a Plug-In processed URL request is incorrect, the WebSTAR Web server will now serve the user-defined Error file.

Under previous versions of WebSTAR when a bad URL request (i.e. http://ww.domain.com/bogus.ssi ) was sent to a Plug-In, that Plug-In was responsible for returning an error message to the user saying that the file did not exist. Note that in this situation the defined Error file was not being processed. Now if a Plug-In returns a WSAPI_E_MessageNotHandled from a non-existent file request, the WebSTAR Web server will now handle normal processing of the Error file (instead of just returning a 404 status code).

Additional information on WebSTAR API Plug-ins

For more information about how to develop Plug-Ins that work with the WebSTAR server, see:

http://dev.starnine.com

ClearWay's WebSTAR API Plug-In Cookbook:

http://dev.clearway.com/

Manual Contents | Chapter Contents | Previous Page | Next Page