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.


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


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


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.


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

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:

for interface details... click here for parser innerworkings... click here


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 Sample Code 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.


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.


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.
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... click here

Eric Prud'hommeaux, libpics@w3.org, March 96