Querying TLD Policy Data

This document explains how to retrieve the characters from the Top-Level Domain Blacklists and Whitelists.

Context

The TLD policy data is composed of a list of TLDs.

For each of the TLDs, the Whitelist contains the trusted UTF-8 characters and the Blacklist contains the suspect UTF-8 characters.

Prerequisites

Before you start, you must:

Be familiar with the concepts of Top-Level Domain (TLD) and International Domain Name (IDN): see What is the Domain Name Server.

Steps

Create a connection with the InetURIList server.

Example:

RInetUriList uriServer;
uriServer.OpenL();
CleanupClosePushL(uriServer);

Build a TPolicyQueryArgs object.
The constructor takes an URI as its first parameter, which defines which TLD the request is made on.
1. To request a character set, pass the list type (InetUriList::EWhiteList or InetUriList::EBlackList) as the second parameter, and the InetUriList::EPolicyCharSet request type as the third parameter.
  Example:
```
// The TLD is "COM"
_LIT8(KUri, "http://www.nokia.com");

// the query requests the white list character set
TPolicyQueryArgs tldArgs(KUri, InetUriList::EWhiteList, InetUriList::EPolicyCharSet);
```
2. To check whether an URI is unsafe, only pass the InetUriList::EPolicyListType request type as the second parameter.
  Example:
```
// The TLD is "COM"
_LIT8(KUri, "http://www.nokia.com");

// the query requests to check the URI
TPolicyQueryArgs tldArgs(KUri, InetUriList::EPolicyListType);
```
Create a TQueryResults object to store the result.
Example:
```
TQueryResults tldResult;
```

Call the RInetUriList::QueryTldInfoL() method with your query and result structures.

Example:

RInetUriList::QueryTldInfoL(tldArgs, tldResult);

// retrieve the characters
HBufC8* policyData(NULL);
policydata = tldResult.CharSetL();

Close the connection with the InetURIList server.
Example:
```
CleanupStack::PopAndDestroy(&uriServer);
```

Results

The TQueryResults object contains the requested TLD policy data.

With an EPolicyListType request, the results objet contains ETrue is the URI contains suspect characters, EFalse otherwise.
An EPolicyCharSet request, the results objet contains the list of characters of the requested list.

Query example

Here is the combination of the code snippets provided in the above steps:

// Open the connection
RInetUriList uriServer;
uriServer.OpenL();
CleanupClosePushL(uriServer);

// The TLD is "COM"
_LIT8(KUri, "http://www.nokia.com");

// Build a query requesting a character set
TPolicyQueryArgs tldArgs(KUri, InetUriList::EPolicyCharSet);

// Create an object for the results
TQueryResults tldResult;

// Make the query
RInetUriList::QueryTldInfoL(tldArgs, tldResult);

// retrieve the characters
HBufC8* policyData(NULL);
policydata = tldResult.CharSetL();

// [...] 
// process the policy data

// Close the connection
CleanupStack::PopAndDestroy(&uriServer);

Related concepts

WhiteList/BlackList TLD Overview

Related tasks

Modifying TLD Policy Data