Internet Ratings API

The Microsoft Internet Ratings API provides Win32®-based applications with easy access to support PICS-based Internet ratings and related services. These functions provide any application with access to a PICS rating parsing engine, as well as a mechanism for comparing ratings against the user information settings in Internet Explorer 4.0. This API will be available as part of Internet Explorer 4.0.

The functions in the Internet Ratings API set facilitate access to the rating support in the following ways:

• Provides a common interface for parsing and obtaining PICS-compliant rating information. A browser or other application can support ratings with the addition of only a few function calls. By providing task-oriented functions, applications need only make a few function calls to support ratings.
• Eliminates the need for individual applications to define their own control systems. With this API, applications need only find the rating information for a given piece of content. Additional APIs for retrieving some types of Internet ratings are provided.

Overview of Internet Ratings Functions

Note The following overview should be considered a pre-release draft of the API specification.

The PICS specification allows for rating information to appear in HTML tags, in HTTP headers, and on a third-party URL. For performance reasons, each individual browser is responsible for obtaining HTML- and HTTP-based rating information (for details on obtaining these mechanisms, consult the PICS specification).

The following table summarizes the PICS support API functions. This table lists all of the functions for finding, pairing, and comparing rating information.

Function	Description
RatingAccessDeniedDialog	Displays a system dialog box informing the user that access has been denied.
RatingCheckUserAccess	Takes in a PICS rating, parses it, and compares it against what a specified user can see.
RatingEnabledQuery	Specifies whether ratings are on or off.
RatingFreeDetails	Frees a pointer to denial information.
RatingObtainCancel	Cancels a call to RatingObtainQuery.
RatingObtainQuery	Obtains ratings from certain locations and compares them.

Using the Internet Ratings Functions

A browser or other application would typically use the rating functions in the following fashion:

1. The browser starts, and the user connects to the Internet.
2. The user enters a URL.
3. The browser calls the RatingEnabledQuery function. If the function returns S_FALSE, the browser allows access to the content.
4. The browser calls the RatingObtainQuery function and passes the URL. The function checks the local list and then the third-party list or any third-party add-on, if any are activated. If the function finds a rating for the URL, it calls RatingCheckUserAccess with the rating. If RatingObtainQuery does not return an error immediately, eventually the browser's callback function will be called.
5. Meanwhile, the browser searches for a rating label within the content being downloaded from the site. If it finds an HTML/HTTP rating, it calls the RatingCheckUserAccess function.
6. If no rating label is found within the document, the browser calls the RatingCheckUserAccess function with a NULL rating label, to determine whether the user can access unrated content.
7. When both RatingCheckUserAccess and RatingObtainQuery have been called, the browser has received at least one explicit access-allowed or access-denied report. If RatingObtainQuery explicitly allowed or denied access, that result should override any rating found in the document and the user's ability to see unrated content.
8. If access is denied, the browser calls the RatingAccessDeniedDialog function. Depending on the supervisor's response to the dialog box, this function can indicate that access should be allowed after all.
9. If access is allowed, the browser displays the content.

Finding HTML/HTTP Rating Labels

The PICS specification defines the Backus-Naur Form (BNF) syntax for rating information, or rating nuggets. PICS specifies that rating nuggets can appear as part of HTML documents, within the header tags. The PICS specification also allows for rating information to appear as part of the HTTP headers.

For performance and logistic reasons, it is the responsibility of the browser to obtain HTML- and HTTP-level ratings. Details on how to find HTML-based ratings are part of the PICS specification.

Support for HTTP ratings may eventually be provided via URL_Moniker, part of the ActiveX SDK. Details on HTTP ratings and the associated HTTP header are specified by PICS.

The PICS committee may eventually provide reference code for applications that want to find HTML/HTTP-based ratings.