PICS library utilities

/*
**	(c) COPYRIGHT MIT 1996.
**	Please first read the full copyright statement in the file COPYRIGH.
*/

#ifndef CSLAPP_H
#define CSLAPP_H
#include "WWWCore.h"
#include "CSLUtils.h"

CSApp_error

Return codes for those functions which do not return a pointer.

/*
typedef enum {
  CSApp_OK, CSCSApp_done, CSApp_memory, CSApp_file, CSApp_badHandle, 
  CSApp_inconsistentParms, CSApp_badPassword, CSApp_internal, CSApp_allowed, 
  CSApp_denied
} CSApp_error;
*/

CSDisposition_callback

- function to be called by the when Pics receives ratings for a requested document. The callback is called afer the PICS library has decided whether the user should be permitted access to the document.

CSDisposition_criteria - when to call the app

pReq - HTRequest which told libwww to load the document

disposition - CSApp_OK if user should see document, CSApp_denied otherwise

pVoid - void pointer passed to CSApp_registerApp or CSApp_registerReq.

typedef enum {
  CSApp_neverCall = 0, CSApp_callOnBad = 1, CSApp_callOnGood = 2
} CSDisposition_criteria;
typedef CSError_t (CSDisposition_callback)(HTRequest* pReq, CSLabel_t * pCSLabel, 
				   CSUser_t * pCSUser, CSError_t disposition, 
				   void * pVoid);

CSApp.c maintains a list of LoadedUsers. More than one may be loaded at a time as different requests may be associated with different users.

extern CSUser_t * CSLoadedUser_load(char * url, char * relatedName);
extern BOOL CSLoadedUser_add(CSUser_t * pCSUser, char * url);
extern BOOL CSLoadedUser_remove(CSUser_t * pCSUser);
extern BOOL CSLoadedUser_find(char * name);
extern BOOL CSLoadedUser_deleteAll (void);

CSLoadedUser_enum - used to iterate through the loaded users

pCallback - application callback to call with each user

pVoid - passed through to callback

typedef CSError_t (CSLoadedUserCallback)(CSUser_t * pCSUser, 
					 int index, void * pVoid);
extern int CSLoadedUser_enum(CSLoadedUserCallback * pCallback, 
			     void * pVoid);

CSUserList

stores a list of PICS users and the URLs to their descritpion files

CSUserList_load

extern BOOL CSUserList_load(char * url, char * relatedName);

CSUserList_enum

used to iterate through the known users

pCallback - application callback to call with each user

pVoid - passed through to callback

username

url - where to find this user's profile

index

typedef CSError_t (CSUserListCallback)(char * username, char * url, 
		   int index, void * pVoid);
extern int CSUserList_enum(CSUserListCallback * pCallback, void * pVoid);

Registering Users

extern BOOL CSApp_registerDefaultUserByName(char * user, char * password);
extern CSUser_t * CSApp_registerUserByName(char * user, char * password);
extern BOOL CSApp_setDefaultUser(CSUser_t * pCSUser);
extern BOOL CSApp_checkUser(CSUser_t * pCSUser);
extern BOOL CSApp_unregisterDefaultUser(void);
extern BOOL CSApp_unregisterUser(CSUser_t * pCSUser);

application functions

CSApp_registerApp

- register defaults for an application

pCallback - callback to tell app the disposition of header check

criteria - when the app wants the callback

pUserCallback - called when a new user is loaded. It returns:

• 1: load this user and set as default
• 0: load this user
• -1: get rid of it

pVoid - passed through to callback

CSApp_unregisterApp - unregister defaults and free associated memory

typedef int (CSApp_userCallback)(CSUser_t * pCSUser, void * pVoid);
extern BOOL CSApp_registerApp(CSDisposition_callback * pCallback, 
			      CSDisposition_criteria criteria, 
			      CSApp_userCallback * pUserCallback, 
			      void * pVoid);
extern BOOL CSApp_unregisterApp();

CSApp_registerReq

- override defaults for a particular request. It is advisable to use this function, rather than relying on the defaults as it eliminates many problems associated with multiple clients using the same dynamic library. Use CSApp_UnregisterReq for every call to CSApp_RegisterReq.

pReq - pointer to request about to be sent.

rest - see parameters for CSApp_RegisterApp()

CSApp_UnregisterReq - free memory associated with call to CSApp_registerReq

extern BOOL CSApp_registerReq(HTRequest* pReq, CSUser_t * pCSUser, 
			      CSDisposition_callback callback, 
			      CSDisposition_criteria criteria,
			      void * pVoid);

extern BOOL CSApp_unregisterReq(HTRequest* pReq);

extern HTRequest * CSApp_originalRequest(HTRequest* pReq);

MISC

CSApp_disposition - tell PICS if a request is allowd

extern BOOL CSApp_label(HTRequest * pReq, CSLabel_t * pCSLabel);

CSApp_libraryVersion - get current version

CSParseMachRead, CSParseUser, CSParseLabel - HTConverters for parsing to these objects

CSLabel_output - spew canonical form of pCSLabel out to pStream

char * CSApp_libraryVersion(void);

extern HTConverter CSParseMachRead;
extern HTConverter CSParseUser;
extern HTConverter CSParseLabel;

extern int CSLabel_output(CSLabel_t * pCSLabel, HTStream * pStream);

#endif /* CSLAPP_H */

End of Declaration