Apple's CGI Docs

Information of interest to CGI script writers about Apple's personal web server software. The docs on this page are © copyright 1996 Apple Computer.

Basic Usage

All CGIs are expected to reside in the folder selected as the shared Web folder. CGIs can be triggered by specifying the CGI application name in the URL of the request, based on a filename extension of ".cgi" or ".acgi". For example, to run the "Responder" CGI, put the "Responder.cgi" application in the shared Web folder and from a browser, access the URL:

http://www.yourserver.com/Responder.cgi

Path and search arguments are supported using the '$' and '?' delimitters, as in MacHTTP 2.2. The AppleEvent structure is identical to the MacHTTP 2.2 format.

Automated Triggers (Actions)

A basic method of registering actions to trigger CGIs in various cases is also supported. There are currently 3 defined types of automatic triggers: "PRE", "ACTION", and "POST".

"PRE" actions ("pre-processors") are executed before any data has been sent back to the browser, allowing the CGI to return a result for any request and over-riding all subsequent processing. If the pre-processor does not return a response, processing of the request continues normally.

A CGI registered as a "PRE"-processor will receive an event for all incoming requests, regardless of the URL suffix. Multiple pre-processors are allowed, but when any pre-processor returns a result, no subsequent pre-processors will be executed and the result will be returned to the browser.

"ACTION" handlers ("actions") are called in exactly the same manner as basic CGIs, except they are triggered based on the URL suffix rather than by specifying the name of the CGI. When registering an action, you must specify a URL suffix to trigger the CGI.

"POST" actions ("post-processors") cannot return data to be sent to the browser, they are only notified that the request was processed.

All action configuration is handled via AppleEvents. AppleEvents are supported to register, list, and delete actions. Applications that run as actions can either send an event to configure themselves or include a simple configuration AppleScript. These events are supported directly by the Web Sharing server application, not the configuration Control Panel. This means that the server must be running to register actions, but the Control Panel does not need to be open.

Sample AppleScripts are included for registering actions, and they are fairly self-explanatory. All of the events include a single string parameter with fields delimitted by CR/LF. The register and delete events require 3 parameters: "Mapped-Suffix", "CGI-Name", and "Action-Type". The mapped suffix is the URL suffix that will trigger the action, and is unused for "PRE" and "POST" action types. The CGI name is simply the exact name of the CGI application. The action type must be one of "PRE", "ACTION", or "POST".

The list event will return a string that includes each of these 3 parameters for each of the actions registered.

The maximum number of actions that can be registered for a single server is 32. All actions are executed asynchronously.

Web Sharing Compatability Recomendations

We strongly urge developers to include either a self-configuration option which sends the appropriate registration AppleEvents, or a double-clickable AppleScript applet that performs the configuration for the user.

Also, Web Sharing is designed to be a non-obtrusive, background-only application run in a non-dedicated environment. When possible, CGIs should run in the background to limit the interference with the user's foreground environment. CGIs should also start once and remain open, when possible, to avoid launches during normal activity that may appear random to the user.

Reporting Bugs/Incompatabilities

Included in this package is a very simple CGI, "Responder". If/When you encounter problems or incompatabilities with existing CGI applications, you can use Responder to verify that basic CGI processing is being handled correctly on your system and to display parameters being sent to the CGI.

Responder can also be used when you report problems by stating the problem in terms of the behavior relative to Responder, if possible. If this is not possible, then please include a copy of the CGI in question and complete documenation on installation and use along with your error report.

---

© Copyright 1996-98 UserLand Software. This page was last built on 5/9/98; 8:29:39 AM. It was originally posted on 12/28/96; 4:12:03 PM.