RatingObtainQuery function

Note  The Internet Ratings API is deprecated, and will be removed in a future release. Use Windows 8 Family Safety feature instead.

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

The address of a URL whose ratings are to be queried.

dwUserData

The data that is passed to the callback function specified by fCallback.

fCallback

An application-defined function that is called on completion. This function is called in the context of a different thread than the one that called RatingObtainQuery.

dwUserData

The data supplied in the initial call to RatingObtainQuery.

hr

The result of the query. This can be one of the following values.

(S_RATING_ALLOW)

Rating found and access allowed.

(S_RATING_DENY)

Rating found and access denied.

(S_RATING_FOUND)

Rating found; use RatingCheckUserAccess to determine access.

(E_RATING_NOT_FOUND)

Rating or service unavailable; look for ratings from other sources, if possible..

pszRating

The 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

The token that can be used in the RatingAccessDeniedDialog dialog box. This must be freed with a call to RatingFreeDetails.

phRatingObtainQuery

The 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 value otherwise.

Remarks

A browser obtains the URL from the user and calls the RatingObtainQuery 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 from the one that called RatingObtainQuery. While waiting for the callback to be called, browsers might be able 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 non-Microsoft ratings, and look for the HTML/HTTP-level ratings.

Requirements