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:
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.
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.
CGIErr CGISendFileData ( APIData apidata, FSSpec *theFile, Boolean includeHeader, const char *setMIMEType )
Return a file to the client.
CGIErr CGIGetIndexedParameter ( APIData apidata, CGIParameterKey whichParam, void *index, OSType *type, UInt32 *dataSize, void **theParameterData )
CGIErr CGIGetParameterInfo ( APIData apidata, CGIParameterKey whichParam, OSType *type, UInt32 *dataSize )
Get type (CGI AE only) and size of data associated with the specified parameter.
CGIErr CGISetParameter ( APIData apidata, CGIParameterKey whichParam, OSType type, void *buffer, UInt32 *bufferSize )
Set one of the server's parameters.
CGIErr CGISetIndexedParameter ( APIData apidata, CGIParameterKey whichParam, void *index, OSType type, void *buffer, UInt32 *bufferSize )
CGIErr CGIStrToHTTPMethod ( char *theString, HTTPMethod *theHTTPMethod )
Return the enumerated value corresponding to the HTTP method identified by theString.
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.
const char * CGIGetHTTPStatusString ( UInt16 statusCode )
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.
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)."
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."
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.
CGIErr CGIResetResFile ( APIData apidata )
Reset the current resource fork to the one in use before the previous call to CGIWSAPIUseMyResFile
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.
CGIErr CGIGetDocumentRoot ( APIData apidata, FSSpec *theFSSpec )
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.
CGIErr CGIRegisterAction ( APIData apidata, char *pluginName, char *actionTag )
CGIErr CGIRegisterTypeMapping ( APIData apidata, char *pluginName, char *actionTag, char *suffix, OSType fileType, OSType creatorType, char *mimeType )
CGIErr CGIRegisterAdminURL ( APIData apidata, const char *adminURL )
Register an URL to use to access your administrative role
CGIErr CGIRegisterAccessControl ( APIData apidata )
Register as an access control handler. The CustomCGIAccessControl function will be called when needed to perform the access control.
CGIErr CGIRegisterFilter ( APIData apidata )
Register as a filter. The CustomCGIFilter function will be called when needed to perform the filtering.
CGIErr CGIGiveTime ( APIData apidata, UInt32 ticksToSleep, Boolean useWNE )
Give time for other processes (both internal to the app and other applications).
CGIErr CGIRequestIdleTime ( APIData apidata, UInt32 ticksToSleep )
long CGIGetRefCon ( APIData apidata )
void CGISetRefCon ( APIData apidata, long newRefCon )