|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-F14A2252-7D7B-5631-9796-3C9AC54014E7" xml:lang="en"><title>Repetitive |
|
13 Search</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>When a new search-sort asynchronous operation is successful, a unique ID |
|
15 is returned to the client, which is referred as query ID. This query ID can |
|
16 be used to repeat the same search-sort query. </p> |
|
17 <section><title>Required background</title> <p>To do a repetitive search operation, |
|
18 that is searching messages using a query ID, you must first get the query |
|
19 ID of that search operation. </p> </section> |
|
20 <section><title>Introduction</title> <p>Every new search-sort asynchronous |
|
21 query that is successful is assigned with a unique 32 bit integer value, which |
|
22 is referred to as a <xref href="GUID-01500959-E1C8-3491-B8F1-0D2F0512CC16.dita"><apiname>query ID</apiname></xref>. This query ID is |
|
23 used to initiate the same search-sort operation (initiate a repetitive query) |
|
24 in future. The query ID can be retrieved using the <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita#GUID-5D956759-5D21-3715-916E-F7E703172762/GUID-1893C3C7-4F77-3630-B115-A161CCA2665A"><apiname>CMsvSearchSortOperation::GetQueryIdL()</apiname></xref> function. </p> <p><b>Marking</b> </p> <p>When the search-sort cache reaches its maximum size the message server |
|
25 deletes the least recently used query to accommodate a new one. However, there |
|
26 may be some queries and their results which the client wants to keep in the |
|
27 cache, irrespective of how frequently they are being used. </p> <p>Such queries |
|
28 can be marked by the client to indicate to the Messaging server that the query |
|
29 should not be disposed from the search-sort cache when the cache is full. |
|
30 Marked queries are considered for deletion only if all of the remaining queries |
|
31 are also marked. </p> <p>To mark a query ID, use the <codeph>TBool aMarkQuery</codeph> parameter |
|
32 in the <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita#GUID-5D956759-5D21-3715-916E-F7E703172762/GUID-6C81A72A-3BEC-3D18-9CAD-46E9309C3FEB"><apiname>CMsvSearchSortOperation::RequestL()</apiname></xref> function in |
|
33 your client application. </p> <codeblock id="GUID-EED135A5-C141-5525-9C0C-DCF318040C46" xml:space="preserve">IMPORT_C void RequestL (CMsvSearchSortQuery* aQuery, TBool aMarkQuery, TRequestStatus& aQueryStatus, TInt aIterator=0)</codeblock> <p><b>Unmarking</b> </p> <p>To unmark a query ID, use the CMsvSearchSortOperation::UnmarkQuery() |
|
34 function in your client application. </p> <codeblock id="GUID-1C27E207-33F0-5F64-81FC-C50BF257BCB7" xml:space="preserve">IMPORT_C TInt UnmarkQuery (const TInt aQueryId )</codeblock> <fig id="GUID-7D09EFAE-67B3-5142-A6EF-F9D86E39414F"> |
|
35 <title> Repetitive search request process </title> |
|
36 <image href="GUID-E9F08BCA-39F6-55D3-8974-BD0FFB90DE11_d0e287390_href.png" placement="inline"/> |
|
37 </fig> </section> |
|
38 <section><title>Procedure</title> <ol id="GUID-E149145A-A3CB-5CE9-9484-9A7B41E9D302"> |
|
39 <li id="GUID-9D17EF5C-BCA1-5FAE-BE69-DDF6B441F4A5"><p>To get a query ID, complete |
|
40 the steps from 1 to 10 in <xref href="GUID-3F938A76-3F27-56ED-BB3D-0E7EC4ACFB9C.dita">New |
|
41 Search</xref>. </p> </li> |
|
42 <li id="GUID-CD3AABCA-4A90-5B1C-8D77-A2E76161DF2A"><p>Get the query ID from |
|
43 step 10 and start the search operation using the query ID as the search parameter. </p> </li> |
|
44 </ol><codeblock xml:space="preserve">void CSearchsortExample::SeachSortRequestByQueryIdL() |
|
45 { |
|
46 //1. Create a session with message server |
|
47 // NOTE: CMsvSession::OpenSyncL requires a &MMsvObserver parameter. This example assumes that |
|
48 // CSearchSortExample implements MMsvObserver. |
|
49 CMsvSession* session = CMsvSession::OpenSyncL(*this); |
|
50 CleanupStack::PushL(session); |
|
51 |
|
52 //2. Create an instance of CMsvSearchSortOperation to perform a |
|
53 //search-sort operation |
|
54 CMSvSearchSortOperation* search = CMSvSearchSortOperation::NewL(*session); |
|
55 CleanupStack::PushL(search); |
|
56 |
|
57 //3. Start the search operation using the query ID as the search parameter |
|
58 TRequestStatus aStatus; |
|
59 search->RequestL(iQueryId, aStatus); |
|
60 |
|
61 //4. Wait for the result |
|
62 User::WaitForRequest(aStatus); |
|
63 |
|
64 //5. Create an array to hold Search-sort results |
|
65 RArray<TMsvId> resultArray; |
|
66 |
|
67 //6. Retrieve the results of the search. The format for the results should be the same as |
|
68 // what is configured in step 2. Else, will leave with the KErrMsvInvalidResultRequest |
|
69 // error |
|
70 TInt err = search->GetResultsL(resultArray); |
|
71 if(ret == KErrNone) |
|
72 { |
|
73 TInt count = resultArray.Count(); |
|
74 } |
|
75 |
|
76 //7. Store the query ID. This ID can be used in repetitive search queries. |
|
77 iQueryId = search->GetQueryIdL(); |
|
78 |
|
79 CleanupStack::PopAndDestroy(2); //search, session |
|
80 }</codeblock> </section> |
|
81 <example><title>Search-sort example</title> <p><xref href="GUID-B26A4743-F331-5AC3-A40A-28B14B785857.dita">SearchSortExample: |
|
82 Enhanced Search and Sort for Message Store </xref> </p> </example> |
|
83 <section><title>See also</title> <p>For conceptual information on search-sort |
|
84 APIs, see <xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita">Search-Sort |
|
85 Introduction</xref>. </p> </section> |
|
86 </conbody></concept> |