RatingObtainQuery Function

---

Encapsulates the process of checking ratings.

Syntax

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

Parameters

pszTargetUrl

Address of a 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:

dwUserData	Data supplied in the initial call to RatingObtainQuery.
hr	Result of the query. This can be one of the following values: S_OK Rating found and access allowed. S_FALSE Rating found and access denied. Error codes 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 hr 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.

Return Value

Returns S_OK if successful, or an error code otherwise.

Remarks

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.

Function Information

Windows NT	Use version 4.0
Windows	Use Windows 95 and later
Header	Ratings.h
Import Library	Msrating.lib
Minimum availability	Internet Explorer 4.0