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:
  • 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