# How to get Started Writing a PICS complient App

## Library Name Prefix

In an effort to eliminate name conflicts and clarify code, all Pics library functions and data types are prepended with CS (for Content Selection). All source files are also prefixed with CS to avoid module collision. Library interface headers are prefixed with CSL (for Library), as in CSLUtils.h and CSLApp.h.

## Components

The libpics library is divided into two components, accessible through two interfaces:

- CSLUtils - a minimal set of files providing parsing capabilities for PICS labels and Machine-readable service descritpions.
- CSLApp - component library for building PICS applications on top of libwww. It provides the application with automatic label requests, parsing of the results, user management, and document authorization.

# CSLUtils

The CSLUtils interface provides access to the basic parser, and its component parsing objects, labels, machine-readable service descritpions, sample user profiles.

### Implementation

This interface is intended to be used by including the component .c and .h files in the user's project. It relies on a small subset of the libwww, namely the HTUtils portion. These functions provide string, list and chunk functionality. The funtions required by these modules are listed in HTFuncs.html.

### Interface

The primary purpose for the CSLUtils interface is to provide parsing capablilities for PICS labels. LablPars.c provides an example of this usage.

### How to parse

- create parser callbacks
  - targetCallback
  - LLErrorHandler
- assign memory functionality
- call parser with some or all of the text to be parsed

### parser callbacks

The parser passes through the passed text, building a data structure containing all the parsed information, making callbacks to the parser when it passed to a new data structure or encounters an error.

### target callbacks

While the parser is reading and filling data structures, it keeps track of what data type it is currently filling. Whenever this target data changes, it call back to the application. This allows the application to check the data that has just been read, or allocate space for the new object. The most common use of this would be to abort when label data comes through with a value that is out of range for the user.

### error handler

The error handler gets called with all parsing problems and data inconsistancies. It is intended to provide the interface to the user. The return values tells the parser to abort or continue parsing.

### memory functionality

All allocation in libwww or libpics goes through the macros HT_?ALLOC and HT_FREE. The macros are assigned to HTMemory functions in HTUtils. The developer may subsititue macros for their own proprietary memory system, or the ANSI malloc functions. Alternatively, the aplication may employ the macros and provide the HTMemory functions, either through the library module HTMemory.c, or in their own application.

### calling the parser

The life cycle of a parse object is as fillows:

- Creation - a parse obejct is created to parse PICS labels, service descriptions, or user profiles.
- Parsing - the parser gets called with the object data as it comes in. The data may be passed in one chunk, but that may not fit network applications.
- Parser destruction - the parser is destroyed, leaving the object that was parsed.
- Object destruction - the object is finally destroyed, recaliming all the memory associated with the above operations.

for interface details... for parser innerworkings...

# CSLApp

The CSLApp provides a library interface for an application based on libwww. You must first understand how to write an application on top of the W3C Reference Library (libwww).

For details on how to use the library, you should look at the CSLApp.html.

The Line-Mode Browser uses the CSLApp interface to libpics. The steps involved in adapting the Line-Mode Browser to libpics are outlined in steps.

## Mechanism

When libwww is about to send out a request to a server, it calls Pics to send a request for Pics ratings. The text of the request is based on the desired URL and the current service. This request may accompany the URL request or may go to a different server.

If the request goes to the same server, ie. accompanies the URL request, the ratings come back ahead of the requested data. When Pics recieves an answer to a service request, it determines whether the URL should be permitted. If there is a callback assiciated with this request, Pics calls the callback to allow the app to override this descision. If no callback is associated with the request, Pics checks to see if there is a default callback for the application. If either of these callbacks is called, the user or services associated with this request or this app may change. If the forbidden disposition remains, the request is marked with a Forbidden (403) error and the remaining network traffic is killed with a call the HTNet_kill.

If the ratings must be acquired from another server, the current request is set to 0 priority and a second request is generated to send the ratings request. Once Pics recievs the results of the ratings request, the accompanying URL request is either killed off, or restored to high priority which enables the request to be sent. When the data returns, the request is already marked as allowed and the request passes on to the app.

## Steps

This quick guide takes you through the basic steps necessary to create your own PICS complient application:

1. Define a user type

   The application must do the fillowing: See the interface in CSLApp.html for details.

2. Load a User
3. Register your application with PICS
4. Register a request with PICS
5. When to free Objects

## User profile

The CSUser module is a special module in that defines the the parsing and use of a user profile. It is intended to serve as an example, not reference code, as there is no specification for a PICS user. To furthur it's usability, the password is not encrypted. Possibly a field that encrypts the password and checks the validity of the rest of the document will be used here in the future. In the meantime, it is reccomended that the CSUser.cmodule be replaced by a proprietary one.

## Load a PICS user

This user is kept around for PICS to inspect when creating label requests and checking values on returns.

## Register an application

This sets of the application's callbacks and default user.

## Register request

The application may have different callbacks and different users associated with different users associated with different requests. This is more robust than defaulting to the user specified in the application registry.

## When to free Objects

This is a short set of recommendation on when to free objects in memory.

Parsers
  These should be destroyed as soon as the object they are parsing is created.

PICS Labels
PICS service descritpions
User profiles
  These may be should be around for the duration of the application's use of the PICS library, though they can be freed at any time if they are not used by an ongoing request

for furthur details...