<?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);