|
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-3F938A76-3F27-56ED-BB3D-0E7EC4ACFB9C" xml:lang="en"><title>New |
|
13 Search</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>This tutorial provides the steps to perform new search on messages (mainly, |
|
15 on email messages). </p> |
|
16 <section><title>Introduction</title> <p>You can perform the following types |
|
17 of search on messages (mainly, on email messages): </p> <ul> |
|
18 <li id="GUID-5851CB02-D769-546E-B748-E6C1E0C1EB8C"><p> <b>Simple search</b> </p> <p>In |
|
19 a simple search, you use only one message field as a search criteria in a |
|
20 search request. The single message field can be: to, from, cc, size, time, |
|
21 message type, message status, priority, attachment type or message body. For |
|
22 example, search for all emails sent to <i>Sam</i>. </p> </li> |
|
23 <li id="GUID-3F4B645D-3A6A-5ED8-AF07-41F02D20F551"><p> <b>Combined search</b> </p> <p>In |
|
24 a combined search, you use more than one message field as a search criteria |
|
25 in a search request. The message fields can be a combination of: to, from, |
|
26 cc, size, time, message type, message status, priority, attachment type, and |
|
27 message body. </p> <p> <b>Note:</b> You can use maximum of five message parts |
|
28 as a search criteria in a combined search. </p> <p>For a combined search, |
|
29 the <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita#GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7/GUID-D5AC69E9-75E0-3179-B12B-1D9521684D4D"><apiname>CMsvSearchSortQuery::AddSearchOptionL()</apiname></xref> function can |
|
30 be called more than once depending on the message fields you use in the search |
|
31 query. For example, if you have to search all messages from sender <i>Albert</i>, |
|
32 with <b>subject</b> <i>Invitation</i>, then you must call the <xref href="GUID-E49C2AFE-5793-37A6-9A08-2A1DD5CCA160.dita"><apiname>AddSearchQueryOptions</apiname></xref> function |
|
33 twice. </p> <p>However, you can use any functions of the <xref href="GUID-F2882FAD-A108-342E-8E35-039C83EFEF55.dita"><apiname>TMsvSearchSortQuery</apiname></xref> class |
|
34 only once in each combined search query. </p> </li> |
|
35 </ul> <p><b>Iterative method</b> </p> <p>You can enable an iterative method |
|
36 in simple and combined searches: </p> <ul> |
|
37 <li id="GUID-855C5460-41A4-5946-9973-67624AFFE3D6"><p> <b>Iterative</b> </p> <p>The |
|
38 iterative method allows a client to access the search-sort results sequentially |
|
39 one at a time. It is useful when a client cannot, or does not want to provide |
|
40 the memory to receive an array of results. </p> </li> |
|
41 <li id="GUID-0EA3F74E-E3AA-5DCE-A400-B8D1DA8E998B"><p> <b> Non-iterative</b> </p> <p>This |
|
42 method retrieves the complete results of the query in a single array. It requires |
|
43 sufficient RAM on the client-side. This is particularly useful for queries |
|
44 that return small subset of results. </p> </li> |
|
45 </ul><note> You specify the method with the <codeph>TInt aIterator</codeph> parameter |
|
46 when the client sends a query to the Message Server. By default, the value |
|
47 is zero (<codeph>0</codeph>) which indicates the non-iterative method. You |
|
48 must set it to <codeph>1</codeph> to get specify the iterative method.</note> <fig id="GUID-B440387E-2A93-5DF0-9E81-79FCA72AB5C8"> |
|
49 <title> New search-sort request process </title> |
|
50 <image href="GUID-21E43B0E-85C7-536E-83A5-E829820775BF_d0e287157_href.png" placement="inline"/> |
|
51 </fig> </section> |
|
52 <section><title>Simple search</title> <ol id="GUID-40D841C8-004A-5E15-AB18-DD1E3D9C0164"> |
|
53 <li id="GUID-90D2E877-B63F-57C5-9601-47CC2AE67325"><p>Create a search-sort |
|
54 query using the <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita#GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7/GUID-B39D5F47-158A-38C8-8552-B3B5581554F7"><apiname>CMsvSearchSortQuery::NewL()</apiname></xref> function. </p> </li> |
|
55 <li id="GUID-F140F72C-3314-5F79-8F00-5E518CE2A2CF"><p>Configure the query |
|
56 by setting parameters, such as the directory to search in, the format for |
|
57 the results, whether to search for whole or part words, whether to use wild |
|
58 cards, the case sensitivity, the values and fields to search and the sorting |
|
59 options. </p> </li> |
|
60 <li id="GUID-5DBE5827-C1C4-5F38-9F43-76DEFD7FA70E"><p>Add the search-sort |
|
61 operation using the search query as a parameter using the <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita#GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7/GUID-D5AC69E9-75E0-3179-B12B-1D9521684D4D"><apiname>CMsvSearchSortQuery::AddSearchOptionL()</apiname></xref> function. |
|
62 There are three versions of the <xref href="GUID-99504AB6-680F-3D96-BA10-CF04D8C23554.dita"><apiname>AddSearchOptionL()</apiname></xref> function, |
|
63 each of which takes a different parameter type: </p> <ol id="GUID-9E468043-DDA7-53D3-A859-1EA1588ABFB5"> |
|
64 <li id="GUID-B73CCE8B-B404-553A-AE55-F16BAE3BDCC6"><p>Descriptor: For searching |
|
65 on sender, recipient list (cc, to, bcc), subject, date and date range. </p> </li> |
|
66 <li id="GUID-3A0E35A3-FE7A-5853-94FA-7247F92DBBB5"><p>Integer: For searching |
|
67 message size and size range. </p> </li> |
|
68 <li id="GUID-B026C578-BC3F-51C8-AA60-F1EE42B58E10"><p>Boolean: For searching |
|
69 on priority (high, medium and low), attachment types, message status. </p> </li> |
|
70 </ol> <p> Note: If necessary, enable sorting of search result in ascending |
|
71 or descending order on the message part added in the query. </p> </li> |
|
72 <li id="GUID-79E1C31B-D45A-5F24-8761-A789005A77A0"><p>Create a session with |
|
73 the Messaging server using the <xref href="GUID-2DA04D96-F0AD-3FDC-9E36-1C27D889AF4B.dita"><apiname>CMsvSession</apiname></xref> class. </p> </li> |
|
74 <li id="GUID-1159ADC2-1226-575E-BA82-3ECE7010630A"><p>Create a search-sort |
|
75 operation using the <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita"><apiname>CMsvSearchSortOperation</apiname></xref> class. </p> </li> |
|
76 <li id="GUID-0FC467F8-F7F1-5FEA-9CBC-5EF7E756834C"><p>Start the search-sort |
|
77 operation by calling 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 |
|
78 and passing the query as a parameter. Do not include an iterator parameter. |
|
79 It will default to zero (non-iterative). </p> </li> |
|
80 <li id="GUID-5C94A9EF-88F1-5B71-9D7A-2EF7C69D77AB"><p>Wait for the Messaging |
|
81 Server to perform the search. </p> </li> |
|
82 <li id="GUID-D2EAE048-D5CA-5728-967E-4830873E11DE"><p>Create an array for |
|
83 storing the results of the search. </p> </li> |
|
84 <li id="GUID-8258A7BA-DF95-59B9-B9C9-AEDE61EFEEA7"><p>Retrieve the results |
|
85 from the search into the array using the <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita#GUID-5D956759-5D21-3715-916E-F7E703172762/GUID-1D6974D1-FF31-3B7C-A726-47A8510E9819"><apiname>CMsvSearchSortOperation::GetResultsL()</apiname></xref> function. </p> </li> |
|
86 <li id="GUID-0B0C26C5-6FA7-5CFA-8C5B-9CEB5C7BC5C0"><p>Get the query ID of |
|
87 the search from the Messaging server, if necessary, for later use using the <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita#GUID-5D956759-5D21-3715-916E-F7E703172762/GUID-989B6F32-DE88-373B-9CA4-5474BB6858CD"><apiname>CMsvSearchSortOperation::GetQueryId()</apiname></xref> function. </p> </li> |
|
88 </ol> <codeblock xml:space="preserve">/** |
|
89 Simple Seachsort request without iterator. |
|
90 */ |
|
91 void CSearchsortExample::SeachSortRequestWithoutIteratorL() |
|
92 { |
|
93 //1. Create an instance of CMsvSearchSortQuery to create a |
|
94 //search-sort query |
|
95 CMsvSearchSortQuery* searchQuery = CMsvSearchSortQuery::NewL(); |
|
96 CleanupStack::PushL(searchQuery); |
|
97 |
|
98 //2. Configure the query. |
|
99 //Search-sort operation is performed on a specified folder. |
|
100 //(e.g, on INBOX, SENT ITEMS, |
|
101 //DRAFT, OUTBOX or any user created folder). Needs to set the value of the folder entry. |
|
102 searchQuery->SetParentId(KMsvRootIndexEntryIdValue); |
|
103 //Set the type of result expected out of the search-sort operation. |
|
104 searchQuery->SetResultType(EMsvResultAsTMsvId); |
|
105 searchQuery->SetWholeWord(ETrue); |
|
106 searchQuery->SetCaseSensitiveOption(ETrue); |
|
107 searchQuery->SetWildCardSearch(EFalse); |
|
108 |
|
109 //3. Add search option |
|
110 _LIT( KMsgTo, “david@nokia.com”) ; |
|
111 searchQuery->AddSearchOptionL(EMsvTo, KMsgTo, EMsvEqual); |
|
112 // Add sort option |
|
113 searchQuery->AddSortOptionL(EMsvSize, EMsvSortAscending); |
|
114 |
|
115 //4. Create a session with message server |
|
116 // NOTE: CMsvSession::OpenSyncL requires a &MMsvObserver parameter. This example assumes that |
|
117 // CSearchSortExample implements MMsvObserver. |
|
118 CMsvSession* session = CMsvSession::OpenSyncL(*this); |
|
119 CleanupStack::PushL(session); |
|
120 |
|
121 //5. Create an instance of CMsvSearchSortOperation to perform a |
|
122 //search-sort operation |
|
123 CMSvSearchSortOperation* search = CMSvSearchSortOperation::NewL(*session); |
|
124 CleanupStack::PushL(search); |
|
125 |
|
126 //6. Start the search operation using the query as a parameter |
|
127 TRequestStatus aStatus; |
|
128 CleanupStack::Pop(searchQuery); |
|
129 // ownership of searchQuery is passed to SearchSortOperation |
|
130 search->RequestL(searchQuery, ETrue, aStatus); |
|
131 |
|
132 //7. Wait for the result |
|
133 User::WaitForRequest(aStatus); |
|
134 |
|
135 //8. Create an array to hold Search-sort results |
|
136 RArray<TMsvId> resultArray; |
|
137 |
|
138 //9. Retrieve the results of the search. The format for the results should be the same as |
|
139 // what is configured in step 2. Else, will leave with the KErrMsvInvalidResultRequest |
|
140 // error |
|
141 TInt err = search->GetResultsL(resultArray); |
|
142 if(ret == KErrNone) |
|
143 { |
|
144 TInt count = resultArray.Count(); |
|
145 } |
|
146 |
|
147 //10. Get the query ID. This ID can be used in repetitive search queries. |
|
148 iQueryId = search->GetQueryIdL(); |
|
149 |
|
150 CleanupStack::PopAndDestroy(2); //search, session |
|
151 } </codeblock></section> |
|
152 <section id="GUID-AE684DF2-5BF3-5B87-8C10-6F69C87622CA"><title>Combined search</title> <p>To |
|
153 create a combined search, add an additional search options in step 3. </p> <codeblock id="GUID-E85BCF64-B96D-5B2C-A4B4-E55B3B4AC83B" xml:space="preserve"> //3. Add search option |
|
154 _LIT( KMsgTo, “david@nokia.com”) ; |
|
155 searchQuery->AddSearchOptionL(EMsvTo, KMsgTo, EMsvEqual); |
|
156 //Add additional option(s) for combined search. |
|
157 TInt size = 100; |
|
158 searchQuery->AddSearchOptionL(EMsvSize, size, EMsvGreaterThanOrEqual); // Integer value search |
|
159 searchQuery->AddSearchOptionL(EMsvAttachment, ETrue); // boolean value search |
|
160 </codeblock> </section> |
|
161 <section id="GUID-0553ACB4-0ABD-5EC8-B7BC-D3217373064B"><title>Iterative search</title> <p>To |
|
162 create an iterative search, specify an iterative parameter at step 6. </p> <codeblock id="GUID-130C7E2A-157A-5D2E-97D9-DCF7CBBD0301" xml:space="preserve"> // 6. Start the search operation using the query as a parameter |
|
163 // Specify the iterative method |
|
164 const TInt KIterativeSearch = 1 ; |
|
165 TRequestStatus aStatus; |
|
166 CleanupStack::Pop(searchQuery); |
|
167 // ownership of searchQuery is passed to SearchSortOperation |
|
168 search->RequestL(searchQuery, ETrue, aStatus, KIterativeSearch); |
|
169 |
|
170 // 9. The results of an iterative search must be retrieved from the message server one at a time |
|
171 |
|
172 // Retrieve the results of the search one at a time |
|
173 |
|
174 TMsvId result; |
|
175 //GetNextResultL returns the number of results remaining in the search. |
|
176 while( search->GetNextResultL( result ) ) |
|
177 { |
|
178 // process result |
|
179 } |
|
180 </codeblock> </section> |
|
181 <example><title>Search-sort example</title> <p><xref href="GUID-B26A4743-F331-5AC3-A40A-28B14B785857.dita">SearchSortExample: |
|
182 Enhanced Search and Sort for Message Store </xref> </p> </example> |
|
183 <section><title>See also</title> <p>For conceptual information on search-sort |
|
184 APIs, see <xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita">Searching |
|
185 and Sorting Messages</xref>. </p> </section> |
|
186 </conbody></concept> |