WebSTAR 4 Manual & Technical Reference

Manual Contents | Chapter Contents | Previous Page | Next Page

Using WebSTAR Plug-In Services

Many of StarNine's WebSTAR Plug-Ins provide services , meaning that other Plug-Ins can use their features. Plug-ins can take advantage of the functionality of other Plug-Ins and work together, f or example, WebSTAR SSI calls WebSTAR Data Cache to cache static data. Third-party Plug-Ins may also support services.

You can call the standard WebSTAR Plug-Ins according to the instructions below. Be sure to do a "preflight" to make sure that the Plug-In is installed, and deal with the errors if it is not.

Calling WebSTAR Auto BinHex

At WebSTAR API Registration time, WebSTAR Auto BinHex registers a service named "BINHEX". This service references routines with the following C prototype:

 

void BinHex (WSAPI_CommandPBPtr pb, char *filename);

where `pb ' is a WebSTAR API parameter block and `filename ' is a Macintosh path (absolute or partial) pointing to the file to be BinHexed and send to the client. The path must also include a trailing ".hqx " extension. For example

 

char * pathToMyFile = ":widgets:widget_info.sit.hqx";

 
WSAPI_CommandPBPtr (myPB, pathToMyFile);

Calling WebSTAR Data Cache

If your Plug-In returns static data, you can take advantage of the WebSTAR Data Cache to have that data stored in memory, rather than requested from your Plug-In at all times.

At WebSTAR API Registration time, WebSTAR Data Cache registers services named "DATACACHE" and "CACHE_PIXO". Both services perform similar functions: to return the contents of a specified file to the caller (retrieving the data from the cache if possible), and to cause the file to be cached for subsequent retrievals.

The DATACACHE service uses a simple WebSTAR API service routine calling interface defined by the following C prototype:

 

char * DataCacheService (WSAPI_CommandPBPtr pb, char *filename, char *mimetype)

The CACHE_PIXO service uses the PIXO interface (http://dev.clearway.com/pixo/) defined by the following C prototype:

 

PIXO_RunResult HandlePIXOService  (PIXO_ParameterBlockPtr pixoPB)

WebSTAR Data Cache now defines some additional and much improved services for handling of cached data. They are:

 

struct cacheFileData {

 
 // INPUTS

 
 char *filename;

 
 // OUTPUTS from Cahce_GetFileData, INPUTS for Cache_ReleaseFileData

 
 unsigned long len; // how many bytes in the file data

 
 char *data; // the file data

 
 unsigned long cookie[4]; // Needed to "unlock" the item. There's enough

 
 // room here for unplanned uses. Our implementation

 
 // only uses cookie[0..1]

};

 
/* Use with Cache_FlushItem to specify the file you want flushed. */

 
struct cacheFlushFile {

 
 char *filename; // the name of the file to flush from memory

};

 
typedef struct {

 
 Cache_Command command;

 
 union {

 
 struct cacheAPIInfo api;

 
 struct cacheFileInfo finfo;

 
 struct cacheFileData data;

 
 struct cacheFlushFile flush;

};

 
} Cache_Params, *Cache_ParamsPtr ;

Calling WebSTAR Proxy

This flexible architecture allows for third party developers to easily augment features in the Proxy or replace the default features that already exists. The Proxy server in WebSTAR Server Suite is not just one Plug-In but rather several Plug-Ins working together. For example, a third party developer could easily replace our WebSTAR Proxy Cache Plug-In with one of their own, or write a "WebSTAR Proxy FTP" Plug-In to handle Proxy FTP requests.

Main "Dispatch" plug-in that accepts connections from browsers, calls the other plug-ins when they need to be called, and then releases the connection. The other plug-ins register themselves with the Dispatcher to let it know they are available.
Multiple "Access" plug-ins. They control which users have access to what kinds of data.
Multiple "Protocol" plug-ins. They handle requests with specific protocols. (e.g.: the HTTP plug-in handles requests for Web information.)
Multiple "Postprocess" plug-ins, which do logging and other after-the-fact processing.
Multiple "Munger" plug-ins, which have an opportunity to change data while it is being delivered to the browser.

In addition to these plug-ins, we have also included a WebSTAR Proxy Cache Plug-In that works with the WebSTAR Proxy HTTP plug-in to cache and manage data that the WebSTAR Proxy Server receives.

Proxy Log Information

You can get and set the WebSTAR Proxy log name and location via AppleEvents:

 

#define kPLEventClass 'PxyL'

 
		// set log file name - typeChar

 
#define kPLEventSetFile 'stlg'

 
		// get the log file name - typeChar

 
#define kPLEventGetFile 'gtlg'

Calling WebSTAR Form Mail

At WebSTAR API Registration time, WebSTAR Form Mail registers three services named "FORMMAIL", "FORMMAIL_MIME" and "FORMMAIL_SSI". The service "FORMMAIL" uses the following C prototype to pass parameters needed to send mail:

 

void FormMail (WSAPI_CommandPBPtr pb, char *from, char *to, char *subject, char *body, char *host);

The service "FORMMAIL_MIME" uses the following C prototype to pass strings to become MIME-encoded:

 

void FormMailMime (WSAPI_CommandPBPtr pb, char *data);

The service "FORMMAIL_SSI" uses the following C prototype to receive text from the WebSTAR SSI #exec piservice command.

 

char *FORMMAIL_SSI(WSAPI_CommandPBPtr pb, char *text)

Calling WebSTAR SSI

At WebSTAR API Registration time, WebSTAR SSI registers two services named "SSISend " and "SSIParse ". These services references routines with the following C prototype:

 

char *Service(WSAPI_CommandPBPtr pb, char *text)

Both services perform SSI processing on the null-terminated text parameter. The SSISend service will send the results back to the client via WSAPI_SendHTTPData() . The SSIParse service will return the results to the caller as a null-terminated string. The caller must dispose of the result string via WSAPI_FreeMemory .

Service routines must be defined as follows to be a valid target of this exec command extension:

 

char *Service (WSAPI_CommandPBPtr pb, void *param);

If no character value is returned by the service, it is assumed that the service routine inserted any results directly into the HTTP output stream (via the WSAPI_SendHTTPData call). Otherwise, the character string returned by the service is processed by SSI, sent to the client, and then disposed of (via the WSAPI_FreeMemory call).