Grant's CGI Framework
Documentation: API

Version: 2.0d6
Release Date: Tuesday, October 14, 1997
Expires no later than: December 31, 1997

Important: THIS DOCUMENTATION IS INCOMPLETE AND PROBABLY A BIT INACCURATE

It is subject to change as the API matures.
Feedback and contributions are encouraged:

grantcgi@list.nisto.com

or grant@achilles.net

Be aware that any of the functions which return a CGIErr may return
CGIErr_Unimplemented if the function has not been implemented for the
type of plug-in or application you are compiling (e.g., some services
are only available to plug-ins, or specific types of plug-ins, while
others may be only available to CGIs).

Most of the CGI API functions require an APIData structure to be
passed in to them. You should never have to directly access or modify
the contents of that structure.

SENDING DATA

CGISendData

CGIErr CGISendData ( APIData apidata, void *theData, UInt32 dataSize, Boolean sendMore )

Important: This function can only be used within the context of CustomCGIProcess.

Returns theData to the server application (for transmission to the remote client).
This function can be called many times on the same CGI event.
If you get an error from this function, the client connection has probably closed
and you can send no more data so you should halt processing.

theData

is a pointer to the data to be returned to the server.

dataSize

is the number of bytes to be read from theData.

sendMore

must be true if you are going to send more data on the same CGI event, false if this is the last chunk of data to be sent.

CGISendFileData

CGIErr CGISendFileData ( APIData apidata, FSSpec *theFile, Boolean includeHeader, const char *setMIMEType )

Return a file to the client.

theFile

a valid FSSpec to the file which is to be sent. Only the data fork will be sent.

includeHeader

if true, an httpHeader will be constructed for the file and returned as well. The client connection will be closed once the file has been sent, so this is basically a 'ReturnFileToClient' call with no other data to be sent. If including the header, this function will determine if the client has made a "HEAD" request and return just the HTTP header if that is the case. If false, just the file data will be returned.

theMIMEType

if NULL, the type mapping will be automatically done by this function (default is text/html). (only applicable to includeHeader).

CGIGetIndexedParameter

CGIErr CGIGetIndexedParameter ( APIData apidata, CGIParameterKey whichParam, void *index, OSType *type, UInt32 *dataSize, void **theParameterData )

CGIGetParameterInfo

CGIErr CGIGetParameterInfo ( APIData apidata, CGIParameterKey whichParam, OSType *type, UInt32 *dataSize )

Get type (CGI AE only) and size of data associated with the specified parameter.

CGISetParameter

CGIErr CGISetParameter ( APIData apidata, CGIParameterKey whichParam, OSType type, void *buffer, UInt32 *bufferSize )

Set one of the server's parameters.

whichParam

4byte key identifying the specific parameter to SET.

type

type of data; is only used by AE CGIs.

buffer

the data to set the parameter to.

bufferSize

size in bytes of the data in the buffer.

CGISetIndexedParameter

CGIErr CGISetIndexedParameter ( APIData apidata, CGIParameterKey whichParam, void *index, OSType type, void *buffer, UInt32 *bufferSize )

whichParam

4byte key identifying the specific parameter to SET.

index

type

type of data; is only used by AE CGIs.

buffer

the data to set the parameter to.

bufferSize

size in bytes of the data in the buffer.

CGIStrToHTTPMethod

CGIErr CGIStrToHTTPMethod ( char *theString, HTTPMethod *theHTTPMethod )

Return the enumerated value corresponding to the HTTP method identified by theString.

theString

a C string identifying the HTTP method.

theHTTPMethod

will be set to the enumerated value corresponding to the HTTP method identified by theString; defaults to GET if no match found.

HTTP HEADER

CGIGetHTTPHeader

CGIErr CGIGetHTTPHeader ( APIData apidata, UInt16 theHTTPStatusCode, const char *statusMsg, const char *messageID, Boolean includeDate, UInt32 lastModified, UInt32 expiresDate, Boolean includeMIME, const char *contentType, UInt32 contentLength, const char *contentLanguage, const char *contentEncoding, const char *location, const char *extraHeaderLines, char **theHeader, UInt16 *theHeaderLength )

theHeader - will be set to point to a new Ptr buffer containing the header string.

statusMsg

must be a valid C format string.

messageID

should be a unique application-defined alphanumeric identifier.

includeDate

will cause the "Date:" header field to be included using the current date/time.

lastModified

mac format date indicating when the data was last modified/updated.

expiresDate

mac format date indicating when the data expires (when it needs to be reloaded).

contentType

MIME type specifier.

contentLength

total size in bytes of the data being returned (not including the header).

contentLanguage

ISO language identifier(s) (e.g., "en" for English)

contentEncoding

encoding format above the content type (usually compression) extraHeaderLines - must be a set of CRLF-terminated header lines with no blank lines. ("<label>: <content>CRLF"...)

theHeaderLength

if not NULL, will be set to the length in bytes of theHeader string.

CGIGetHTTPStatusString

const char * CGIGetHTTPStatusString ( UInt16 statusCode )

STATUS

CGIConnectionStatus

CGIErr CGIConnectionStatus ( APIData apidata, HTTP_STATUS *status )

status - is set to the status of the HTTP connection associated with the thread that this call is made from.

APPLE EVENTS

CGISendAppleEvent

CGIErr CGISendAppleEvent ( APIData apidata, AppleEvent *theAppleEvent )

Sends an async, AppleEvent. "IMPORTANT for WebSTAR Mac plug-ins!!!! For WebSTAR plug-ins, the server generates the appropriate return ID for your AppleEvent, so the value you supply to the AECreateAppleEvent call will be overwritten. If you are making this call as part of processing a message other than "WSAPI_Run" (i.e., that is NOT associated with a HTTP connection), you should note that your plug-in can have at most one pending event because ALL of your other message handlers run in a separate context from a HTTP connection and share a single return ID that WebSTAR uses to connect the asynch event reply to your plug-in."

"You are responsible for disposing any platform-specific data associated
with your message after it has been sent (i.e., the event and address
descriptors on Macs)."

CGIReceiveAppleEvent

CGIErr CGIReceiveAppleEvent ( APIData apidata, CGI_AE_ResultPtr *theAEResultInfo )

Receive an AppleEvent response "WSAPI 1.0 Beta Draft - May 2, 1996

If you send an interprocess communication message (e.g., an AppleEvent under Mac O/S) and expect and asynchronous reply received by and delivered through the server to your thread of execution, you should call this routine once you expect the reply (i.e., after you've sent the IPC message). If the server receives the message reply before the timeout period defined by the server, your reply will be returned in the msg parameter. If not, msg will be null and an error code will be returned by the function.

Important: for WebSTAR Mac plug-ins!!!! When the AppleEvent is returned to you, you MUST resume the AppleEvent with a call to AEResumeTheCurrentEvent. (See IM VI, 6-84) This will pass control to the handler you specify (should be a UPP to a procedure in your plug-in.) The handler must process the AE to completion. It is VERY important that your plug-in do this in a timely fashion and NOT yield time to other threads. (Well, yielding seems like a bad thing at this point because it might allow another plug-in to begin processing an event in parallel, and the AE manager is NOT reentrant and cannot process 2 events at once!) This means no callbacks until the event is handled!
If msg is not null, you are responsible for disposing the msg data structure, plus any data passed to you in it if necessary."

RESOURCE FORK HANDLING

CGIUseMyResFile

CGIErr CGIUseMyResFile ( APIData apidata )

Set the application/plug-in file's resource fork as the current resource file.

Important: You must not call any of the CGI API functions that may yield (or any other function that might yield) before calling CGIResetResFile after using this function.

CGIResetResFile

CGIErr CGIResetResFile ( APIData apidata )

Reset the current resource fork to the one in use before the previous call to CGIWSAPIUseMyResFile

CGIGetMyFSSpec

CGIErr CGIGetMyFSSpec ( APIData apidata, FSSpec *theFSSpec )

Fill out an already allocated FSSpec with the current process' location. The provided FSSpec will be untouched if an error occurs. Thanks to Gregory S. Combs for providing most of this function.

CGIGetDocumentRoot

CGIErr CGIGetDocumentRoot ( APIData apidata, FSSpec *theFSSpec )

CGIGetServerFSSpec

CGIErr CGIGetServerFSSpec ( APIData apidata, FSSpec *theFSSpec )

Get the FSSpec of the web server application.

Warning: DO NOT DEPEND ON SERVER RELATIVE FILE LOCATIONS! The document root, plug-ins folder, etc. might not be in the same folder as the server application. Not all servers use the same setup as WebSTAR.

SERVICE REGISTRATION

CGIRegisterAction

CGIErr CGIRegisterAction ( APIData apidata, char *pluginName, char *actionTag )

CGIRegisterTypeMapping

CGIErr CGIRegisterTypeMapping ( APIData apidata, char *pluginName, char *actionTag, char *suffix, OSType fileType, OSType creatorType, char *mimeType )

CGIRegisterAdminURL

CGIErr CGIRegisterAdminURL ( APIData apidata, const char *adminURL )

Register an URL to use to access your administrative role

CGIRegisterAccessControl

CGIErr CGIRegisterAccessControl ( APIData apidata )

Register as an access control handler. The CustomCGIAccessControl function will be called when needed to perform the access control.

CGIRegisterFilter

CGIErr CGIRegisterFilter ( APIData apidata )

Register as a filter. The CustomCGIFilter function will be called when needed to perform the filtering.

IDLE/PERIODIC TASKS

CGIGiveTime

CGIErr CGIGiveTime ( APIData apidata, UInt32 ticksToSleep, Boolean useWNE )

Give time for other processes (both internal to the app and other applications).

ticksToSleep

suggested amount of time to give. if nil, default will be used.

useWNE

determines if time will be given to other applications (via WNE), or just to other threads in the current application. (only applicable when compiling as a CGI).

CGIRequestIdleTime

CGIErr CGIRequestIdleTime ( APIData apidata, UInt32 ticksToSleep )

API USER REFERENCE (REFCON)

CGIGetRefCon

long CGIGetRefCon ( APIData apidata )

CGISetRefCon

void CGISetRefCon ( APIData apidata, long newRefCon )