|
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-32C1FC8B-F7D2-5275-BDF2-0D662551294C" xml:lang="en"><title>Search-Sort |
|
13 Introduction</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>In Symbian OS v9.3 and earlier, when a search or sort query is made by |
|
15 a client, Message Server searches in the permanent file store (a proprietary |
|
16 formatted file), and returns the result to the client. </p> |
|
17 <p>From Symbian^3 onwards Message Server operates with the SQL |
|
18 database to store index entries. With the SQL database implementation the |
|
19 Message Server makes a query on the SQL index entry table, and returns the |
|
20 result to the client. </p> |
|
21 <p>The Messaging Middleware module provides an enhanced API for searching |
|
22 and sorting messages. This API can be used only when the SQL database is used |
|
23 to store the index entries. The API has the following features: </p> |
|
24 <ul> |
|
25 <li id="GUID-ACA12109-0146-5E75-A966-7BC6BA760A02"><p>Combined search (combination |
|
26 of more than one simple search criteria) </p> </li> |
|
27 <li id="GUID-945EFB6D-82CC-5E96-9487-37A6F0687C5A"><p>Search based on whole |
|
28 and partial words </p> </li> |
|
29 <li id="GUID-AA68CB16-94F8-56D4-98A7-2FB7A0372D24"><p>Case sensitive search </p> </li> |
|
30 <li id="GUID-FBDF167C-9DFF-5AF6-9352-17750D4649E3"><p>Wildcard search </p> </li> |
|
31 <li id="GUID-82B8AF61-5EE5-5DA1-96C8-EF94267D034D"><p>Count of total search |
|
32 results </p> </li> |
|
33 <li id="GUID-42BFEC5C-0703-51C5-952B-ACA571BDAFBD"><p>Single level sorting |
|
34 of search results </p> </li> |
|
35 <li id="GUID-ABDF3B62-0EDC-5256-858C-C958D84D00D1"><p>Iterative mechanism |
|
36 for clients to access the search and sort results sequentially. </p> </li> |
|
37 </ul> |
|
38 <p>The following sections include basic information on the search-sort functionality, |
|
39 which is important to understand before using the search-sort APIs: </p> |
|
40 <ul> |
|
41 <li id="GUID-CF2F2278-378A-5CA8-8E0A-5B7300CDCAA6"><p><xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita#GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C/GUID-F682B9C3-8D9C-586B-94E5-67A24EB90180">Description</xref> </p> </li> |
|
42 <li id="GUID-28C84BAA-BD23-5A95-9D9F-402754208292"><p><xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita#GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C/GUID-98960254-25D6-5F63-9788-255205B6D2BB">Search-sort API summary</xref> </p> </li> |
|
43 <li id="GUID-B928EB9A-8999-5E5F-9C61-C0DFF9EDA401"><p><xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita#GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C/GUID-995B61DB-FB68-591E-8810-1DA96C882435">Advantages</xref> </p> </li> |
|
44 <li id="GUID-89A87B95-6A21-5CBD-B682-439E233AB29E"><p><xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita#GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C/GUID-014C08BD-7FFC-5D2B-A107-316A70D52D12">Limitations</xref> </p> </li> |
|
45 </ul> |
|
46 <section id="GUID-F682B9C3-8D9C-586B-94E5-67A24EB90180"><title>Description</title> <p>The |
|
47 search-sort functionality is based on the client-server architecture. The |
|
48 Messaging Middleware module provides an advanced search-sort capability if |
|
49 the index entries are stored in an SQL database. </p> <p>The client creates |
|
50 a search-sort query, and passes it to the Message Server. The Message Server |
|
51 searches in the search-sort cache to check whether the query is a repetitive |
|
52 query (a query that was already requested in the past and for which a query |
|
53 ID is maintained in the search-sort cache) or a new query. </p> <p>If it is |
|
54 a repetitive query, the Message Server gets the index entry from the SQL database, |
|
55 and provides the search result to the client. </p> <p>If it is a new query, |
|
56 the Message Server stores the search query in the cache, and passes the query |
|
57 to the SQL database. </p> <p>In both the cases, the Message Server gets the |
|
58 index entry from the SQL database, passes the result to the client, and maintains |
|
59 the query in the search-sort cache. </p> <p>The iterative method can be used |
|
60 for searching and sorting a new or a repetitive search query. </p> <p>The |
|
61 following table provides detailed information on the fields supported in the |
|
62 search-sort operation: </p> <table id="GUID-0A7F291E-2B4E-5632-9D54-7C83CA8D1CE0"> |
|
63 <tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/> |
|
64 <thead> |
|
65 <row> |
|
66 <entry>Operation</entry> |
|
67 <entry>Header</entry> |
|
68 <entry>Body</entry> |
|
69 <entry>TMsvEntry</entry> |
|
70 </row> |
|
71 </thead> |
|
72 <tbody> |
|
73 <row> |
|
74 <entry><p> <b> Searching</b> </p> </entry> |
|
75 <entry><p>To, cc, bcc, from, subject </p> </entry> |
|
76 <entry><p>Body part, whole and partial word (case sensitive and insensitive, |
|
77 whole word, wildcard) </p> </entry> |
|
78 <entry><p>Attachment type, read, unread, new flag, priority, size, MTM type, |
|
79 iDescription, iDetails, and date and time. </p> </entry> |
|
80 </row> |
|
81 <row> |
|
82 <entry><p> <b> Searching with explicit sorting</b> </p> </entry> |
|
83 <entry><p>To, cc, bcc, from, subject </p> </entry> |
|
84 <entry><p>-</p> </entry> |
|
85 <entry><p>Attachment type, read, unread, new flag, priority, size, MTM type, |
|
86 iDescription, iDetails, and date and time. </p> </entry> |
|
87 </row> |
|
88 <row> |
|
89 <entry><p> <b>Sorting</b> </p> </entry> |
|
90 <entry><p>To, cc, bcc, from, subject </p> </entry> |
|
91 <entry/> |
|
92 <entry><p>Attachment type, read, unread, new flag, priority, size, MTM type, |
|
93 iDescription, iDetails, and date and time. </p> </entry> |
|
94 </row> |
|
95 </tbody> |
|
96 </tgroup> |
|
97 </table> <p><b>Key terms</b> </p> <dl> |
|
98 <dlentry> |
|
99 <dt>Iterator</dt> |
|
100 <dd><p>An iterator is a method that allows a client to access the search and |
|
101 sort results sequentially. An iterator is useful when a client does not want |
|
102 to provide the memory to receive an array of results. </p> </dd> |
|
103 </dlentry> |
|
104 <dlentry> |
|
105 <dt>Search-sort cache</dt> |
|
106 <dd><p>Search-sort cache contains frequently requested search-sort queries. |
|
107 By default, this cache is set to 20 percent of the index entry cache. </p> <p>For |
|
108 more information the search-sort cache, see <xref href="GUID-45CA1787-F41F-5AA0-9508-B9D683602D41.dita">Search-Sort |
|
109 Cache</xref>. </p> </dd> |
|
110 </dlentry> |
|
111 </dl> </section> |
|
112 <section id="GUID-98960254-25D6-5F63-9788-255205B6D2BB"><title>Search-sort |
|
113 API summary</title> <p>Use the following APIs available in <filepath>msgs.dll</filepath> for |
|
114 searching and sorting messages: </p> <fig id="GUID-B16C2CC4-4269-5F23-88C3-33E87F198D88"> |
|
115 <title> High level class diagram of new search-sort API |
|
116 </title> |
|
117 <image href="GUID-0E91173A-BA80-5817-866A-7A284573EBCE_d0e285207_href.png" placement="inline"/> |
|
118 </fig> <ul> |
|
119 <li id="GUID-9A2D5945-9D5F-5235-BA4F-500CFE5B2CF0"><p> <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita"><apiname>CMsvSearchSortOperation</apiname></xref> </p> <p>The <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita"><apiname>CMsvSearchSortOperation</apiname></xref> class is used in the client application for enhanced search-sort operations |
|
120 on the message store. </p> <p>This class can be used for the following: </p> <ul> |
|
121 <li id="GUID-7FAD5025-F94D-5824-BFD7-BDFCB83C4F2D"><p>To run a simple or complex |
|
122 search-sort request. </p> </li> |
|
123 <li id="GUID-94DFA54C-B9B6-5154-BF09-46A45DFCCD1E"><p>To repeat an earlier |
|
124 search-sort operation by using the <xref href="GUID-47DEF0FA-908B-31E4-A493-64FE7468F1D1.dita"><apiname>queryId</apiname></xref>. </p> </li> |
|
125 <li id="GUID-FBB74619-7822-5EC8-BD69-E7D2F2943896"><p>To receive results either |
|
126 in one chunk using an array or one after the other using an iterative method. </p> <note> The |
|
127 search-sort results can be received as a list of <xref href="GUID-A4B1F874-27C0-3BB6-9D29-C35C75A5DB98.dita"><apiname>TMsvId</apiname></xref> or <xref href="GUID-5A23B804-2C06-3407-9D48-1BFB212D699F.dita"><apiname>TMsvEntry</apiname></xref> objects.</note></li> |
|
128 </ul> </li> |
|
129 <li id="GUID-B757296A-97BD-5816-99BD-7897900CA1F4"><p> <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita"><apiname>CMsvSearchSortQuery</apiname></xref> </p> <p>The <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita"><apiname>CMsvSearchSortQuery</apiname></xref> class |
|
130 is used in the client application to create a search-sort query. It has an |
|
131 interface to add or set the query criteria on various message parts. </p> <p>This |
|
132 class provides the following search options: </p> <ul> |
|
133 <li id="GUID-F6ABCDEC-C50F-53BA-8817-CA88444765E7"><p>Case sensitive search |
|
134 (<xref href="GUID-4F6E4BC7-B77B-390D-BF08-58DF5EF2A959.dita"><apiname>SetCaseSensitiveOption</apiname></xref>) </p> <p>By default this option |
|
135 is set to false. </p> </li> |
|
136 <li id="GUID-C33F20AC-8F74-5CF6-9446-02227F274E59"><p>Whole word search (<xref href="GUID-D95D1E2A-8D0C-3509-8C51-C36DA28E304D.dita"><apiname>SetWholeWord</apiname></xref>) </p> <p>By |
|
137 default this option is set to false. </p> </li> |
|
138 <li id="GUID-F9BDA832-A1B8-5596-B619-2A54936D48FB"><p>Wildcard search (<xref href="GUID-BB9B7771-194B-3629-937C-0C829A339463.dita"><apiname>SetWildCardSearch</apiname></xref>) </p> <p>Allow |
|
139 the use of the asterisk (*) and question mark (?) wildcards. By default this |
|
140 option is set to false. </p> </li> |
|
141 <li id="GUID-ACAC32F4-9E34-5A47-A5CB-F9B5D2AE1235"><p>Subfolder search (<xref href="GUID-B06EB103-6ECA-39F0-A3F0-B99D7314CF3C.dita"><apiname>SetSubFolderSearch</apiname></xref>) </p> <p>Include |
|
142 the entries within the subfolders in the search result. By default this option |
|
143 is set to false. </p> <note> The subfolder option is valid only for a search |
|
144 query. </note> </li> |
|
145 <li id="GUID-AD053845-DB7D-5447-AD38-A348E51B6DE6"><p>Explicit single level |
|
146 sort (using the <codeph>TMsvMessagePart aMessagePart</codeph> parameter |
|
147 in the <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita#GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7/GUID-D4A0638E-61AE-3F7D-AB84-D3285F2D4539"><apiname>CMsvSearchSortQuery::AddSearchOptionL</apiname></xref> function. </p> <p>Sorting |
|
148 on one particular message part. </p> </li> |
|
149 </ul> <p>The <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita"><apiname>CMsvSearchSortQuery</apiname></xref> class is used with the <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita"><apiname>CMsvSearchSortOperation</apiname></xref> class |
|
150 when requesting a new search-sort operation. </p> <note type="important"> By |
|
151 default, the search query results are not sorted. To receive a result in a |
|
152 sorted order, you must send a sort request by using the <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita#GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7/GUID-CE8F4E20-B1A9-32BF-B1FB-6F4E6CB88C2A"><apiname>CMsvSearchSortQuery::AddSortOptionL()</apiname></xref> function. |
|
153 Sort options can be used with search options when creating a search-sort query. </note></li> |
|
154 <li id="GUID-6DAE4181-212F-5988-AD0E-C1BF20503952"><p> <xref href="GUID-D9BB2EF0-262F-3BCF-8F48-F40FE0D4C107.dita"><apiname>TMsvMessagePart</apiname></xref> </p> <p>The <xref href="GUID-D9BB2EF0-262F-3BCF-8F48-F40FE0D4C107.dita"><apiname>TMsvMessagePart</apiname></xref> is |
|
155 an enumeration type class that contains all parts of the message, including |
|
156 index entry and message header. Searching or sorting is done based on the <xref href="GUID-D9BB2EF0-262F-3BCF-8F48-F40FE0D4C107.dita"><apiname>TMsvMessagePart</apiname></xref> class. </p> </li> |
|
157 <li id="GUID-EFEB6199-FD8A-55F4-9524-02E5C4A65488"><p> <xref href="GUID-A60B4636-F309-3FD6-8D12-D4EE3AC6BC58.dita"><apiname>TMsvSearchSortResultType</apiname></xref> </p> <p>The <xref href="GUID-A60B4636-F309-3FD6-8D12-D4EE3AC6BC58.dita"><apiname>TMsvSearchSortResultType</apiname></xref> is an enumeration class. The client uses <xref href="GUID-A60B4636-F309-3FD6-8D12-D4EE3AC6BC58.dita"><apiname>TMsvSearchSortResultType</apiname></xref> to |
|
158 specify if the search and sort results are returned as <xref href="GUID-A4B1F874-27C0-3BB6-9D29-C35C75A5DB98.dita"><apiname>TMsvId</apiname></xref> or <xref href="GUID-5A23B804-2C06-3407-9D48-1BFB212D699F.dita"><apiname>TMsvEntry</apiname></xref>. </p> </li> |
|
159 <li id="GUID-B07DA71A-4906-5EAB-8A4F-A103EB6F259F"><p> <xref href="GUID-9EC5FF8F-55BF-3D4B-BF1E-6221509E2583.dita"><apiname>TMsvRelationOp</apiname></xref> </p> <p>The <xref href="GUID-9EC5FF8F-55BF-3D4B-BF1E-6221509E2583.dita"><apiname>TMsvRelationOp</apiname></xref> is |
|
160 an enumeration type class that is used to provide relational operations between |
|
161 the search criteria value and the value in the message part of a message. </p> <p>For |
|
162 example, equal to, greater than, greater than or equal to, less than, and |
|
163 less than or equal to. </p> </li> |
|
164 <li id="GUID-0DA7A049-9FCA-5F7C-9C69-E357BBD5525D"><p> <xref href="GUID-94A91DF4-2362-3042-A230-79B4B294B2F6.dita"><apiname>TMsvSortOrder</apiname></xref> </p> <p>The <xref href="GUID-94A91DF4-2362-3042-A230-79B4B294B2F6.dita"><apiname>TMsvSortOrder</apiname></xref> is |
|
165 an enumeration type class that is used to provide the sorting options for |
|
166 sorting queries. The search or sort results can be sorted in ascending or |
|
167 descending order. </p> </li> |
|
168 </ul> </section> |
|
169 <section id="GUID-995B61DB-FB68-591E-8810-1DA96C882435"><title>Advantages</title> <p>The |
|
170 following are the advantages of the enhanced search-sort functionality: </p> <ul> |
|
171 <li id="GUID-D6B66EA5-4E18-5065-8502-7FD78C0147C8"><p>Search messages by the |
|
172 following fields: </p><note> Most of the following fields are applicable to |
|
173 email messages: </note> <ul> |
|
174 <li id="GUID-77DB4B4B-DD60-5164-974A-BD892702FD2B"><p>Sender, recipient list |
|
175 (cc, to, bcc), subject </p> </li> |
|
176 <li id="GUID-C16729FC-8517-59BF-AEE7-CEF4B6929AC9"><p>Mail size and size range </p> </li> |
|
177 <li id="GUID-FDA2E776-CE39-55E6-900E-8EBE826EBABC"><p>Date and date range </p> </li> |
|
178 <li id="GUID-24535174-207A-5095-ACCB-38F0A2B4704B"><p>Message type (SMS, Email, |
|
179 MMS, and BIO message) </p> </li> |
|
180 <li id="GUID-C190645B-B338-5C37-B506-BF783144923D"><p>Priority (high, medium, |
|
181 and low) </p> </li> |
|
182 <li id="GUID-D8804E92-44D5-5730-A09F-BE5EE62FB505"><p>Attachment types (linked |
|
183 attachment and file attachment) </p> </li> |
|
184 <li id="GUID-68D9C896-B8B1-5FA4-B833-8A7E9E2A09D0"><p>Message status </p> <p>For |
|
185 example, New, Read, Unread, and so on. </p> </li> |
|
186 </ul> </li> |
|
187 <li id="GUID-D381A082-643C-502A-99A9-1813C2FE5B8D"><p>Search messages containing |
|
188 a specified string in a specified message part. </p> </li> |
|
189 <li id="GUID-CB9D7CD8-41BF-55EA-B867-5C39192FC984"><p>Search within subfolders |
|
190 of the parent folder. </p> </li> |
|
191 <li id="GUID-194B52B2-B443-51A2-A7CB-4595CEE0101E"><p>Provides combined search |
|
192 and sort options to the client. </p> </li> |
|
193 <li id="GUID-21C4E9F2-CF3C-552D-8A4E-E2714060DF87"><p>Provides explicit single |
|
194 level of sorting with implicit sort by data and time. </p> </li> |
|
195 <li id="GUID-2137FD0D-97F5-58DA-BDC0-2E39EFFA750F"><p>Allows client to implement |
|
196 more versatile UI views. </p> </li> |
|
197 <li id="GUID-CECCA668-AEBD-5A26-AF0A-D591A7128F65"><p>Returns total number |
|
198 of search-sort count without sending the resultant data. For example, the |
|
199 number of unread messages in the inbox. </p> </li> |
|
200 <li id="GUID-308007D7-B0AC-5E6E-8EB9-2CD56214BED1"><p>Provides good RAM performance |
|
201 for repetitive search-sort requests, as the Messaging framework maintains |
|
202 a search-sort cache for frequently used search-sort requests. </p> </li> |
|
203 </ul> </section> |
|
204 <section id="GUID-014C08BD-7FFC-5D2B-A107-316A70D52D12"><title>Limitations</title> <p>The |
|
205 following are the limitations of the advanced search and sort functionality: </p> <ul> |
|
206 <li id="GUID-1361069B-D79B-5F37-B6D2-5730B73152B4"><p>The search-sort operation |
|
207 for a specific value in a specific message part is supported, but searching |
|
208 for a specific value in all message parts is not supported. </p> </li> |
|
209 <li id="GUID-F0E732EC-D4D5-53AE-A2F2-F09ADF134426"><p>Index entry is migrated |
|
210 to SQL. The header and body part are yet to be migrated to SQL. So the iterative |
|
211 method is supported only if the message parts in the index entry are used |
|
212 in creating the search-sort query. </p> </li> |
|
213 <li id="GUID-56127926-2AD8-50CE-81F3-E2CC5AE89EB7"><p>The following are not |
|
214 supported in the iterative method because the limitations of SQL: </p> <ul> |
|
215 <li id="GUID-F61AF937-A39E-5276-AE13-AEA2F48BF0C3"><p>Accessing the next set |
|
216 of values, that is, next <b>n</b> values (results). </p> </li> |
|
217 <li id="GUID-17F483B6-427F-59CD-8C47-88D5542E765B"><p>Accessing the previous |
|
218 value or the previous set of values. </p> </li> |
|
219 <li id="GUID-0323A0FD-DED7-5B44-B53E-565727B59E81"><p>Accessing a random value |
|
220 or a random set of values. </p> </li> |
|
221 </ul> </li> |
|
222 <li id="GUID-C567013B-A385-50B4-BC30-325BB2B073DB"><p>Multi level sorting |
|
223 is not supported. </p> </li> |
|
224 <li id="GUID-B0BB3E72-1C5F-5F44-AA79-170B4BC2CFD2"><p>A search query can use |
|
225 a maximum of five message parts as search criteria in a combined search. </p> </li> |
|
226 <li id="GUID-AFC8222E-ACF6-5F11-9D2C-773E9149473E"><p>Sorting on message body |
|
227 is not supported. </p> </li> |
|
228 <li id="GUID-62916475-9920-5196-9DB3-4F9C517F759B"><p>Search-sort operation |
|
229 cannot be performed on all the message parts present in index entry. The supported |
|
230 list consists of message parts present in message header, message body and |
|
231 a partial list of message parts from index entry. See the <xref href="GUID-D9BB2EF0-262F-3BCF-8F48-F40FE0D4C107.dita"><apiname>TMsvMessagePart</apiname></xref> enumeration |
|
232 class for the supported message parts. </p> </li> |
|
233 </ul> </section> |
|
234 </conbody><related-links> |
|
235 <link href="GUID-45CA1787-F41F-5AA0-9508-B9D683602D41.dita"><linktext>Search-Sort |
|
236 Cache</linktext></link> |
|
237 <link href="GUID-B26A4743-F331-5AC3-A40A-28B14B785857.dita"><linktext>Example code</linktext> |
|
238 </link> |
|
239 </related-links></concept> |