Reference

This section contains detailed reference information about the functions in the Microsoft Internet Ratings API.

RatingAccessDeniedDialog

HRESULT RatingAccessDeniedDialog(
    HWND hwndParent, 
    LPCTSTR pszUsername, 
    LPCTSTR pszContentDescription, 
    LPVOID pRatingDetails
); 

Displays a modal dialog box telling the user that access to the requested content is denied. The supervisor can set an option that adds controls to the dialog box; these controls would allow a supervisor to enter a user name and password to override the rating and allow access.

• Returns one of the following values:

  S_OK	The supervisor entered the password. Access should be allowed.
  S_FALSE	The user is still denied access to the content.
  Error values	An error occurred.

hwndParent

Handle of the parent window for the modal dialog box.

pszUsername

Address of a string that contains the name of the user who was denied access. If this parameter is NULL, the user name is extracted from the structure specified by pRatingDetails, or the current user name is used.

pszContentDescription

Address of a string that describes the content to which access was denied.

pRatingDetails

Opaque pointer returned by the RatingCheckUserAccess function. This parameter can provide the dialog box with additional information about why access was denied, such as whether the site is considered rated, which ratings exceeded limits, and where the rating was obtained.

See also RatingCheckUserAccess

RatingFreeDetails

HRESULT RatingFreeDetails(
    LPVOID pRatingDetails
); 

Frees the detail information returned by the RatingCheckUserAccess function.

pRatingDetails

Opaque pointer returned by the RatingCheckUserAccess function.

See also RatingCheckUserAccess

RatingCheckUserAccess

HRESULT RatingCheckUserAccess(
    LPCTSTR pszUsername, 
    LPCTSTR pszURL,
    LPCTSTR pszRatingInfo, 
    LPBYTE pData, 
    DWORD cbData, 
    LPVOID *ppRatingDetails
); 

Determines whether the user is allowed to view the given content based on the associated rating label. An application calls this function when it finds a rating label.

• Returns one of the following values:

  S_OK	Access is allowed.
  S_FALSE	Access is denied.
  Error values	Content should be considered unrated.

pszUsername

Address of a string that contains the name of the user whose access to the content should be validated. A NULL value means the currently logged on user. For Internet Explorer version 3.0, NULL is the only valid value for this parameter.

pszURL

Address of the URL to which the rating label is to apply. The function uses this parameter to validate the corresponding field in the rating label, to verify that the rating label actually belongs to the URL for which the label was obtained. This parameter can be NULL if a URL is not applicable.

pszRatingInfo

Address of the PICS label to parse and verify (for example, the text between the "content" single quotation marks in the example in Example of HTML Tagged Ratings). This parameter can be NULL if the application cannot find a rating in the content itself; in this case, the function returns a value that indicates whether the user is allowed to see unrated content.

pData and cbData

Address of the content being rated and the length, in bytes, of the content data stream. These parameters may be necessary if the rating itself contains a hash of the data for security reasons. If pData is NULL, the cbData parameter is ignored, and the hash cannot be validated.

ppRatingDetails

Address of a variable that contains a pointer to an opaque data structure that describes in more detail why access to the content is denied. This parameter has meaning only to the RatingAccessDeniedDialog function. This parameter can be NULL, in which case the dialog box created by RatingAccessDeniedDialog cannot report detailed information to the user. If this parameter is not NULL, the application must call the RatingFreeDetails function to free the data, no matter what value the RatingCheckUserAccess function returns or what value is stored in ppRatingDetails.

This function allows ratings of any content type, including CD-ROMs, news groups, Web sites, and so on, provided the client application can find the rating information. The RatingObtainQuery function makes an internal call to the RatingCheckUserAccess function before calling the application's callback function.

See also RatingAccessDeniedDialog, RatingFreeDetails, RatingObtainQuery

RatingEnabledQuery

HRESULT RatingEnabledQuery(void)

Reports whether ratings should be enforced or not. If the supervisor has not configured any restrictions or has temporarily disabled them, the application may allow access to all content and need not call any other rating functions.

• Returns one of the following values:

  S_OK	Ratings are enabled and should be enforced.
  S_FALSE	Ratings are disabled and should be ignored.

RatingObtainCancel

HRESULT RatingObtainCancel(
    HANDLE hRatingObtainQuery
); 

Allows a browser to cancel its request to obtain the rating for a URL.

hRatingObtainQuery

Handle obtained by a previous call to the RatingObtainQuery function.

See also RatingObtainQuery

RatingObtainQuery

HRESULT RatingObtainQuery(
    LPCTSTR pszTargetUrl,
    DWORD dwUserData, 
    void (*fCallback)(
        DWORD dwUserData, 
        HRESULT hres,
        LPCTSTR pszRating, 
        LPVOID lpvRatingDetails
    ), 
    HANDLE *phRatingObtainQuery
); 

Encapsulates the process of checking ratings that appear on a local list, third-party PICS server, or future third-party add-on rating services.

pszTargetUrl

URL whose ratings are to be queried.

dwUserData

Data to be passed to the callback function specified by fCallback.

fCallback

Application-defined function that is called upon completion. This function is called in the context of a different thread than the one that called RatingObtainQuery.

The callback function has the following parameters:

hres	Result of the query. Can be one of the following values: S_OK Rating found and access allowed. S_FALSE Rating found and access denied. Any error values Rating or service unavailable; look for ratings from other sources if possible.
pszRating	Rating information for the document if it is available. (Note that the application can choose to ignore this parameter because RatingCheckUserAccess has already been called to generate the hres parameter).
lpvRatingDetails	Token that can be used in the RatingAccessDeniedDialog dialog box. This must be freed with a call to RatingFreeDetails.

phRatingObtainQuery

Address of a handle that can be used to cancel this operation. This parameter can be NULL if the handle is not needed.

A browser obtains the URL from the user and calls this function. Asynchronously, this function searches for a rating for the specified document. When the search ends, the function calls the application's callback function, on a different thread than the one that called RatingObtainQuery. While waiting for the callback to be called, browsers may choose to download the content but prevent the user from accessing it until the query is resolved.

If RatingObtainQuery returns an error, the application should assume the site is unrated by local and third-party ratings, and look for the HTML/HTTP-level ratings itself.

RatingSetupUI

HRESULT RatingSetupUI(
    HWND hwndParent, 
    LPCSTR pszUsername
); 

Displays a modal dialog box that allows a supervising parent to set levels of restrictions. The RatingCheckUserAccess function uses these settings to compare against rating labels.

hwndParent

Handle of the window handle for the modal dialog box.

pszUsername

Address of a string that contains the name of the user whose settings should be configured. If this parameter is NULL, settings for all users are set. This parameter must be NULL in Internet Explorer version 3.0.

This function ensures that the current user is a supervisor before allowing access to the configuration user interface.