# W3C PICS library Interfaces

Any suggestions or ideas are welcome at libpics@w3.org.

## 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.

  Furthur functionality is provided by:

- CSLabel - access to PICS label structures
- CSUser - sample user profiles
- CSMacRed - machine-readable service descritpions

  Of interest, but no consequence:

- CSParse - how the above three are generated

Every module in the PICS library has a HTML document associated with it containing a detailed description of its interface. See w3c Library Interfaces for instructions on modifying header or html files.

# CSLUtils

The minimal interface to the PICS library is to use it as just a parser. The parser may read a label, machine readable service description, or a user descritpion. The only PICS modules needed for this interface are the parser and a module specific to the object you wish to parse (see the Label parser example). The parser uses list, chunk, and memory management from the libwww modules. See the function list for a list of the needed funtions. These functions are implemented in libwww. To make it easier to genericly integrate CSLUtils with any application, the libwww modules of these functions have been sequestered to HTUtils, along with the necessary headers.

The CSLUtils interface is defined in CSLUtils.html. This contains the definition of primitive data types and ephemoral types, as well as some label request generation functions.

### objects

It defined the following objects needed to employ the parser:

- BVal, FVal, SVal, DVal - boolean and floating values need a structure to convey an unititialized state. The float value also needs to have positive and negative infinity values. BVal and FVal implement this. SVal and DVal are parellel structures for string and date values.
- StateRet - a comprehensive set of error parsing error codes.
- CSParse - holds the state data for iterative calls to the parser. A CSParse object is created with the following:
  - TargetChangeCallback - called whenever the parser switches target data types. For instance, the label parser will do a callback when it encounters a single-label in a service-info. It will do another callback when the single-label is finished and the context is switching back to the service-info.
  - ParseErrorHandler - how the application provides error information to the user and decides which errors allow the parser to attempt to continue.
- CSLabel, CSUser, and CSMachRead - contain the data read by the parser. These objects contain all the data that could be encountered while parsing these objects.
- CSError - a bastardised concatination of the errors encountered in generating and dealing with labels requests.

### label request generation functions

These functions generate label requests given a list of services. These are also implemented for CSUsers

- CSList_acceptLabels
- CSList_getLabels
- CSList_postLabels

## LablPars

LablPars.c demonstrates the use of the CSLUtils interface. The User's guide explains how LablPars uses the CSLUtils interface. HTFuncs.html explains how LablPars provides the list and memory functions required by the parser. Example output is in Simple.html. Another example, that parses .rat files (machine-readable service descriptions), is in RatPars.

## CSLApp

This interface is a superset of the CSLUtils interface. It automates the process of generating label requests for each URL request and checking user profiles to allow or deny access to the URL. It is intended to supplement the libwww and will probably only be usefull to applications based it.

The CSLApp interface is defined in CSLApp.html. This contains the definition of primitive data types and ephemoral types, as well as some label request generation functions.

### objects

It defined the following objects:

- CSApp_callback - this is called whenever libpics determines whether a user is allowed to see a labeld document. The application may use it to inform the user, or allow the user an opportunitiy to switch to a more priviledged identity.
- CSUserList - a list to associate user names with URLs to their profiles.
- CSApp_userCallback - called when a new PICS profile is loaded. It gives the application the opportunity to prompt the user switch to that profile.

### functions

- CSApp_registerApp - called to enable libpics for an application. This sets up default callbacks.
- CSApp_registerDefaultUser - the simplest way to use libpics is to set the default user. This means that an application may have only one user at a time.
- CSApp_registerUser - select a user and return a handle to the app. This is usefull if the app registers a user for each request.
- CSApp_registerReq - associate a user and other parameters with a request.
- CSApp_unregisterReq
- CSApp_unregisterUser
- CSApp_unregisterApp

## CSLabel

CSLL.html Application interface to Label data structures and internals

### objects

- CSLLTC - CSLabel List Target Change. This enum lists the values passed to TargetChangeCallback
- CSLLData - optionally ephemeral container of label data. The contents are available in CSLLSt. The application may treat CSLLData as an ephemeral type and use iterators to access the data.

  TargetChangeCallback and ErrorHandler are subclassed to deal with CSLabels and CSLLTC:

- LabelTargetCallback
- LLErrorHandler

  The CSLabel iterator callback:

- CSLabel_callback

### functions

- CSParse_newLabel - make a CSParse object for parsing labels
- CSParse_deleteLabel - reclaim the above memory
- CSParse_getLabel - get a CSLabel from the CSParse made above
- CSLabel_copy - copy a CSLabel object, useful for iterators
- CSLabel_free

  iterators are a way of accessing CSLabel data:

- CSLabel_iterateServices
- CSLabel_iterateLabels
- CSLabel_iterateSingleLabels
- CSLabel_iterateLabelRatings

  range functions check to see if a user range includes a rating value or range:

- CSLabel_ratingsIncludeFVal - check inclusion of single value
- CSLabel_ratingsIncludeRange - check inclusion of range
- CSLabel_ratingsIncludeRanges - check inclusion of list of ranges

CSLLSt.html Label data internals

### objects

- CSLLData
- ServiceInfo
- Label
- SingleLabel
- LabelRating
- LabelOptions
- Extension
- ExtensionData
- LabelError

### functions

- CSLabel_getCSLLData
- CSLabel_getLabelError
- CSLabel_getLabelOptions
- CSLabel_getServiceInfo
- CSLabel_getServiceName
- CSLabel_getLabel
- CSLabel_getLabelNumber
- CSLabel_getSingleLabel
- CSLabel_getLabelRating
- CSLabel_getRatingName
- CSLabel_getRange

### CSUser

Example user description, not specified in any standard.

CSUser.html Application interface to User data structures and internals

### objects

### functions

CSUserSt.html User data internals

### objects

### functions

### CSMacRed

CSMR.html Application interface to MR data structures and internals

### objects

### functions

CSMRSt.html MR data internals

### objects

### functions

## CSParser

### definition files

- CSParse.html - included by CSParse and the component parsers.
- CSLUtils.html - included by application calling parser.

### objects

- CSParse - the shell parser's context. Made of:
  - NowIn - how the parser keeps track of whether it is in a token, string, etc.
  - Engine - what the parser calls with each token after it and its terminating punctuation is found. This is set by the component parsers.
- StateToken and TargetObject - the data structures that tell the component parsers what to expect and where to place data.

### functions

- CSParse_new - used by label, user, MacRed parses to create parser for their own objects
- CSParse_delete use by app to remove the CSParse object that built a lalel,user, MacRed.
- CSParse_parseChunk - called by app to read a string and generate data structures.