Querying URIs from the URI List

The RInetUriList class provides the following APIs for retrieving the information of URIs present in the list:

• API for retrieving the number of URIs present in the list, based on a given service type and list type:

  TInt Count ( InetUriList::TServiceType aServiceType, InetUriList::TListType aListType )

  If the URI count of both the lists is required, then set aListType parameter to EBlackList and EWhiteList.

• API for retrieving the list type of a given URI:

  TInt GetListType ( const TDesC8& aUri, InetUriList::TServiceType aServiceType, InetUriList::TListType& aListType )

  The list type will be returned through aListType as an out parameter. If the URI is not found, then return type will be KErrUriNotFound.

• API for querying URIs in the list:

  void QueryUriL ( const TQueryArgs& aArgs, MQueryResultsCallback* aQueryCallback, MUriCustomiser* aUriCustomiser =NULL )

  Based on the the TQueryArgs parameter, this API supports different query operations. TQueryArgs is template class which provides four constructors. The argument types for TQueryArgs can be a combination of URI, service type, list type, and match type. The service type is mandatory for the query operation. Based on the TQueryArgs parameter combination, the following types of queries can be performed:

  • Find existence of a URI of a given service type.

  • Find all URIs matching the path of a specified URI and service type.

  • Find all URIs matching the domain name of a specified URI and service type.

  • Find all the URIs matching the prefix path of a specified URI and service type.

  • Find all the URIs matching the suffix path of a specified URI and service type.

  • Find all the URIs of a specified service type and list type.

The aQueryCallback parameter of the QueryUriL API provides a callback interface that needs to be implemented by the calling client. The calling client class should derive from the MQueryResultsCallback class and provide implementation for the MQueryResultsCallback::OnQueryResultsL() function. The optional aUriCustomiser parameter of the QueryUriL API provides a callback interface for URI customisation by scheme/protocol normalization. The calling client should be derived from the MUriCustomiser class and provide implementation for the MUriCustomiser::OnUriCustomisationL() function. Given below are some code samples for performing different queries.

//Create a Uri
_LIT8(KUri, “http://www.symbian.com/symbianos/email/index.html”);

//Create a session with the server.
    RInetUriList uriListObj;
    uriListObj.OpenL();
    CleanupClosePushL(uriListObj);

//Construct TQueryArgs object with Uri, service type
//and match type. 
    TQueryArgs uriArgs(KUri, EBrowser, EDomain);

//Query the Uri and close the session. 
    uriListObj. QueryUriL(uriArgs, this);
    CleanupStack::PopAndDestroy(&uriListObj);

In the above code sample, all the browsing URIs matching with the domain name www.symbian.com is searched from both BlackList and WhiteList, as list type is not specified. The second parameter is a pointer to the client class that implements the OnQueryResultsL() call back function. For each matching URI that is found, the QueryUriL function calls the OnQueryResultsL callback function until it returns EFalse, or until all matching URIs are passed to it.

The match type is a value of enumeration TURIMatch. The searching criteria can be changed by changing the match type.

• If the match type is EExact in the above code sample, only one URI would be returned.

• If the match type is ExactPath, all the URIs that have the same scheme, domain name, and path would be returned. These URIs might be different only in fragments.

• If the match type is EPartialPrefixPath, all the URIs matching the prefix path and scheme will be returned.

  For example, if the incoming URI is http://www.symbian.com/symbianos/, then the following URIs would match if match type is EPartialPrefixPath:

  • http://www.symbian.com/symbianos/email/index.html

  • http://www.symbian.com/symbianos/solutions/solutions.html

• If the match type is EPartialSuffixPath, then all the URIs matching suffix path and scheme will be returned.

  For example, if the incoming URI is http://www.symbian.com/index.html, then the following URIs would match if match type is EPartialSuffixPath:

  • http://www.symbian.com/symbianos/email/index.html

  • http://www.symbian.com/symbianos/index.html

//Create a session with the server.
    RInetUriList uriListObj;
    uriListObj.OpenL();
    CleanupClosePushL(uriListObj);

//Construct TQueryArgs object with service type and 
//match type.
    TQueryArgs uriArgs(EBrowser);

//Query the Uri and close the session. 
    uriListObj. QueryUriL(uriArgs, this, this);
    CleanupStack::PopAndDestroy(&uriListObj);

The above code sample retrieves all browser URIs of both BlackList and WhiteList types. To retrieve all the URIs for all service types, the caller has to loop for all service types. The third argument of QueryUriL indicates that the caller has implemented the OnUriCustomisationL() callback function, and so the URI will be passed to this callback function for normalization before being passed for a query.