Components
The libpics library is divided into two components, accessible through two
interfaces:
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... 
for parser innerworkings... 
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:
The application must do the fillowing: See the interface in CSLApp.html for details.
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.
for furthur details...