<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-402B5633-1E3A-5F24-8C4F-DA5F04D2557C"><title>Querying URIs from the URI List</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>The <xref href="GUID-6F5E2A42-5047-3AB2-9929-D893B88F2BD2.dita"><apiname>RInetUriList</apiname></xref> class provides the following APIs for retrieving the information of URIs present in the list: </p> <ul><li id="GUID-6F99901E-B8A4-5E42-B874-066171E88A69"><p>API for retrieving the number of URIs present in the list, based on a given service type and list type: </p> <p> <codeph>TInt Count ( InetUriList::TServiceType aServiceType,

             InetUriList::TListType aListType )</codeph>  </p> <p>If the URI count of both the lists is required, then set <codeph>aListType</codeph> parameter to <codeph>EBlackList</codeph> and <codeph>EWhiteList</codeph>. </p> </li> <li id="GUID-F4E514BF-BF07-5A4C-8A0D-9121536FB178"><p>API for retrieving the list type of a given URI: </p> <p> <codeph>TInt GetListType ( const TDesC8&amp; aUri,

             InetUriList::TServiceType aServiceType, InetUriList::TListType& aListType

             )</codeph>  </p> <p>The list type will be returned through <codeph>aListType</codeph> as an out parameter. If the URI is not found, then return type will be <codeph>KErrUriNotFound</codeph>. </p> </li> <li id="GUID-50D349EE-CA38-54D8-96AB-FA2AAF4AA6F6"><p>API for querying URIs in the list: </p> <p> <codeph>void QueryUriL ( const TQueryArgs&amp; aArgs,

             MQueryResultsCallback* aQueryCallback, MUriCustomiser* aUriCustomiser =NULL

             )</codeph>  </p> <p>Based on the the <codeph>TQueryArgs</codeph> parameter, this API supports different query operations. <codeph>TQueryArgs</codeph> is template class which provides four constructors. The argument types for <codeph>TQueryArgs</codeph> 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 <codeph>TQueryArgs</codeph> parameter combination, the following types of queries can be performed: </p> <ul><li id="GUID-EDB3E659-648E-52C5-AB8C-D572675163F1"><p>Find existence of a URI of a given service type. </p> </li> <li id="GUID-76B6918F-6085-5DF1-946C-A6899EA61E4C"><p>Find all URIs matching the path of a specified URI and service type. </p> </li> <li id="GUID-733C2073-4619-544E-8E40-66E62D96A9C1"><p>Find all URIs matching the domain name of a specified URI and service type. </p> </li> <li id="GUID-5582DFC2-0C78-5D61-B13A-099F1F185AC7"><p>Find all the URIs matching the prefix path of a specified URI and service type. </p> </li> <li id="GUID-6B6427C9-2099-566C-87E6-D6E9C856B5A6"><p>Find all the URIs matching the suffix path of a specified URI and service type. </p> </li> <li id="GUID-3F62B201-A0AB-599F-BB8E-A287401E2495"><p>Find all the URIs of a specified service type and list type. </p> </li> </ul> </li> </ul> <p>The <xref href="GUID-82F7F1DC-127F-3111-A7F0-9F32744A1CA3.dita"><apiname>aQueryCallback</apiname></xref> parameter of the <xref href="GUID-F57CA961-6151-3FBB-9FAB-4D8F507248E7.dita"><apiname>QueryUriL</apiname></xref> API provides a callback interface that needs to be implemented by the calling client. The calling client class should derive from the <xref href="GUID-5D5672DF-DDB0-336B-9A96-DE7D55B937FE.dita"><apiname>MQueryResultsCallback</apiname></xref> class and provide implementation for the <xref href="GUID-5D5672DF-DDB0-336B-9A96-DE7D55B937FE.dita#GUID-5D5672DF-DDB0-336B-9A96-DE7D55B937FE/GUID-399C8754-C6F0-3ED0-A0E9-12EA1B91068A"><apiname>MQueryResultsCallback::OnQueryResultsL()</apiname></xref> function. The optional <xref href="GUID-AC04057D-75D3-3214-86BD-F20AD98AD6A0.dita"><apiname>aUriCustomiser</apiname></xref> parameter of the <xref href="GUID-F57CA961-6151-3FBB-9FAB-4D8F507248E7.dita"><apiname>QueryUriL</apiname></xref> API provides a callback interface for URI customisation by scheme/protocol normalization. The calling client should be derived from the <xref href="GUID-B29E0EB7-BB4C-3E54-A844-182EBC4B159D.dita"><apiname>MUriCustomiser</apiname></xref> class and provide implementation for the <xref href="GUID-B29E0EB7-BB4C-3E54-A844-182EBC4B159D.dita#GUID-B29E0EB7-BB4C-3E54-A844-182EBC4B159D/GUID-5ECB0068-0EFD-3FB6-B229-C911C912ADA5"><apiname>MUriCustomiser::OnUriCustomisationL()</apiname></xref> function. Given below are some code samples for performing different queries. </p> <codeblock id="GUID-4BAAEEC7-50F9-5561-8322-23956F596A29" xml:space="preserve">//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);

</codeblock> <p>In the above code sample, all the browsing URIs matching with the domain name <i>www.symbian.com</i> 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 <xref href="GUID-5987B8E8-0036-375A-842A-3D424E655593.dita"><apiname>OnQueryResultsL()</apiname></xref> call back function. For each matching URI that is found, the <xref href="GUID-F57CA961-6151-3FBB-9FAB-4D8F507248E7.dita"><apiname>QueryUriL</apiname></xref> function calls the <xref href="GUID-F79918C2-87E2-34CC-915C-E4D322F747F5.dita"><apiname>OnQueryResultsL</apiname></xref> callback function until it returns <codeph>EFalse</codeph>, or until all matching URIs are passed to it. </p> <p>The match type is a value of enumeration <xref href="GUID-BCEF56E7-FB35-385E-8F22-82F13249E524.dita"><apiname>TURIMatch</apiname></xref>. The searching criteria can be changed by changing the match type. </p> <ul><li id="GUID-E7924DE0-462B-5222-B395-7C31DE9348CA"><p>If the match type is <codeph>EExact</codeph> in the above code sample, only one URI would be returned. </p> </li> <li id="GUID-94D88299-BAF1-52D9-A5E3-1C6DB13D7A2E"><p>If the match type is <codeph>ExactPath</codeph>, all the URIs that have the same scheme, domain name, and path would be returned. These URIs might be different only in fragments. </p> </li> <li id="GUID-646AFE86-0B4B-5684-A12F-7857F5D94825"><p>If the match type is <codeph>EPartialPrefixPath</codeph>, all the URIs matching the prefix path and scheme will be returned. </p> <p>For example, if the incoming URI is http://www.symbian.com/symbianos/, then the following URIs would match if match type is <codeph>EPartialPrefixPath</codeph>: </p> <ul><li id="GUID-ED7958FE-3A49-5416-92D3-4C322961D8E7"><p>http://www.symbian.com/symbianos/email/index.html </p> </li> <li id="GUID-7EA3DA47-FAD8-5662-91D8-4451152F12CA"><p>http://www.symbian.com/symbianos/solutions/solutions.html </p> </li> </ul> </li> <li id="GUID-19E488B2-2213-5D16-AF0E-9EBA3927D5FC"><p>If the match type is <codeph>EPartialSuffixPath</codeph>, then all the URIs matching suffix path and scheme will be returned. </p> <p>For example, if the incoming URI is http://www.symbian.com/index.html, then the following URIs would match if match type is <codeph>EPartialSuffixPath</codeph>: </p> <ul><li id="GUID-B4E59EAA-E080-5CC0-B5DA-51F536ABF814"><p>http://www.symbian.com/symbianos/email/index.html </p> </li> <li id="GUID-38EC342F-BEA0-5E71-8C2F-BDFFA46B8315"><p>http://www.symbian.com/symbianos/index.html </p> </li> </ul> </li> </ul> <codeblock id="GUID-6F662156-4B35-5147-8650-8E8A374DBA0D" xml:space="preserve">//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);

</codeblock> <p>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 <xref href="GUID-F57CA961-6151-3FBB-9FAB-4D8F507248E7.dita"><apiname>QueryUriL</apiname></xref> indicates that the caller has implemented the <xref href="GUID-422B212E-FE6B-369F-8A6C-ADF8D3D9A1E2.dita"><apiname>OnUriCustomisationL()</apiname></xref> callback function, and so the URI will be passed to this callback function for normalization before being passed for a query. </p> </conbody></concept>