Grant's CGI Framework
Documentation: CGI Utilities

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).

HTML Form Handling

CGIFormFieldsFromArgs

CGIErr CGIFormFieldsFromArgs ( APIData apidata, char *theString, UInt32 *count, CGIFormField **outFields )

The separator '&' separates individual fields. The delimiter '=' delimits the name and value in a field. For example: "Field 1=some stuff&Another Field=more stuff&Last Field=no stuff" Means that there are 3 fields with names "Field 1", "Another Field" and "Last Field"

theString

the URL-encoded, '&' and '=' delimited, C-format field list string.

count

set to the number of fields found.

outFields

set to an array of field records with the last containing null values.

CGIFormFieldsFindRecord

CGIFormField * CGIFormFieldsFindRecord ( CGIFormField *fieldArray, const char *fieldName )

Returns a pointer to the first form field record, in the given fieldArray, that's name matches the supplied field name.

CGIFormFieldsFindValue

const char * CGIFormFieldsFindValue ( CGIFormField *fieldArray, const char *fieldName )

Returns a pointer to the string containing the value from the field specified by 'fieldName'. Returns a pointer to a null string ("") if the field is not found. The pointer points directly into the form fields array in apidata.

Important: Whatever you do - do not attempt to deallocate the string returned by this function!!!

CGIFormFieldsDispose

void CGIFormFieldsDispose ( APIData apidata, CGIFormField *theFields )

Deallocate memory for theFields array.

UTILITIES

CGIActionIsCGIorACGI

Boolean CGIActionIsCGIorACGI ( APIData apidata )

Returns true if the action parameter is either CGI or ACGI.

Returns false if it is some other action.

CGIHostNameDifferent

Boolean CGIHostNameDifferent ( APIData apidata, char *theHostName, short hostNameLength )

Check to see if the client accessed the server with the correct host name. This is only useful for browsers that include the "Host:" field in their HTTP request. If no host field is found, (or if the server did not supply the full_request data) this function will default to returning false (no difference).

SECURITY

CGIValidateUser

CGIErr CGIValidateUser ( APIData apidata, const char *name, const char *password, const char *realm )

Validate whether or not a specific user should be allowed access based on the server application's security realms.

Returns nil if user is validated.

Note: when compiled as a wsapi plug-in, this function may return WSAPI_E_MessageNotHandled if the server is using an external security validator, such as a security plug-in.

CHARACTER CODING

CGIEncodeURLChars

char * CGIEncodeURLChars ( APIData apidata, const char *theString, OSErr *outErr )

%hex encode all non-alphanumeric characters. IE. '~' (126) becomes '%7E'.

Returns NULL if unable to allocate memory for the encoded string.

theString

is not modified.

outErr

will not be set if it is a NULL ptr.

APPLE EVENTS

CGIPassAppleEvent

CGIErr CGIPassAppleEvent ( APIData apidata, OSType destinationOSCreator )