|
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 reference |
|
11 PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd"> |
|
12 <reference id="GUID-B26A4743-F331-5AC3-A40A-28B14B785857" xml:lang="en"><title>SearchSortExample: |
|
13 enhanced search and sort for Message Store</title><shortdesc>This example demonstrates the enhanced search and sort API for |
|
14 message stores. This API was implemented in Symbian OS v9.5. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody> |
|
15 <section><title>Purpose</title> <p>Prior to v9.5 the Message Store API had |
|
16 limited support for selecting and sorting message records and fields. In v9.5, |
|
17 the API implements more extensive search and sort options. </p> <p>This example |
|
18 demonstrates the new functionality by implementing the following use cases: </p> <ul> |
|
19 <li id="GUID-E9B88EDB-8DD1-5CC2-B6DD-CA8498FE1865"><p>Display the header information |
|
20 for all message entries. </p> </li> |
|
21 <li id="GUID-5D07456E-DEDE-578D-961F-138E9DBD9470"><p>Perform a simple (single |
|
22 search criteria) non-iterative search-sort and display the matching entries. |
|
23 This has the following options: </p> <ul> |
|
24 <li id="GUID-73CAF478-2B69-5883-B7A1-4F8B20D884E8"><p>case sensitivity on |
|
25 / off, </p> </li> |
|
26 <li id="GUID-D158CBA7-4947-589F-9C1E-FFB0E36A8CEF"><p>whole word search on |
|
27 / off. </p> </li> |
|
28 </ul> </li> |
|
29 <li id="GUID-F2FC91DD-8198-53BB-9C77-5DC30C071AE1"><p>Perform a combined (more |
|
30 than one search criteria) non-iterative search-sort and display the number |
|
31 of matching entries. This has the following options: </p> <ul> |
|
32 <li id="GUID-25CDF7E6-9D22-58C8-8832-03B0723A7F6E"><p>case sensitivity on |
|
33 / off, </p> </li> |
|
34 <li id="GUID-35902CB3-B4AF-56D0-937A-A840B3F40CDA"><p>whole word search on |
|
35 / off. </p> </li> |
|
36 </ul> </li> |
|
37 <li id="GUID-54A5DEF1-21F3-5B24-85BA-71450C7E3D2D"><p>Perform an iterative |
|
38 search-sort (searches for entries one at a time) and display the number of |
|
39 matching entries. </p> </li> |
|
40 <li id="GUID-5412D0A2-2A38-5F34-AE9E-AE7940345DDC"><p>Perform a search-sort |
|
41 using a query ID. The query ID is generated by a previous search-sort operation. </p> </li> |
|
42 </ul> <p>Before implementing these use cases, the example creates a POP3/SMTP |
|
43 message store with five message entries. </p> </section> |
|
44 <section><title>Class summary</title><p>The example demonstrates the following |
|
45 classes and enums:</p><p><xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita"><apiname>CMsvSearchSortOperation</apiname></xref> <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita"><apiname> CMsvSearchSortQuery</apiname></xref> <xref href="GUID-D9BB2EF0-262F-3BCF-8F48-F40FE0D4C107.dita"><apiname> TMsvMessagePart</apiname></xref> <xref href="GUID-A60B4636-F309-3FD6-8D12-D4EE3AC6BC58.dita"><apiname> TMsvSearchSortResultType</apiname></xref></p></section> |
|
46 <section id="GUID-9331568B-0BA3-5138-BDCC-65AC225A5328"><title>Download</title> <p>Click |
|
47 on the following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-dbb3813f-c947-4359-805e-eeada16f1dbb.zip" scope="external">searchsortexample.zip</xref></p><p>Click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-dbb3813f-c947-4359-805e-eeada16f1dbb.html" scope="peer">browse</xref> to view the example code. </p> </section> |
|
48 <section id="GUID-F8B3E0E7-FB82-5266-AB40-C1149A782E83"><title>Design |
|
49 and implementation</title> <p><b>Project Implementation</b> </p> <p>The project |
|
50 implements the following classes: </p> <p> <b>CKeyReader:</b> Derived from <codeph>CActive</codeph>. |
|
51 This reads keypresses and calls the appropriate example function. </p> <p> <b>CMessAsyncWaiter:</b> Derived |
|
52 from <codeph>CActive</codeph>. This handles the <codeph>CMsvSearchSortOperation::RequestL()</codeph> asynchronous |
|
53 request. This <codeph>RequestL()</codeph> function takes <codeph>CMessAsyncWaiter::iStatus</codeph> as |
|
54 one of its parameters and then waits on the status. When the search is complete |
|
55 the client is notified of the event's completion by <codeph>CMessAsyncWaiter::RunL()</codeph> being |
|
56 called, after which the example prepares the buffer and displays the results. </p> <p> <b>CSearchsortExample:</b> Derived |
|
57 from <codeph>CBase</codeph> and <codeph>MMsvSessionObserver</codeph>. <codeph>MMsvSessionObserver</codeph> is |
|
58 an interface for notification of events from a Message Server session. </p> <p> <codeph>CSearchsortExample</codeph> implements <codeph>HandleSessionEventL()</codeph> to handle the two event types <codeph>EMsvEntriesCreated</codeph> and <codeph>EMsvServerReady</codeph>. |
|
59 It also creates the SMTP message entries and carries out searching and sorting. </p> <p><b>Simple |
|
60 non-iterative search-sort</b> </p> <p>The example starts by creating a message |
|
61 server session using <codeph>CMsvSession</codeph>, which represents a channel |
|
62 of communication between a client thread (client-side MTM, user interface |
|
63 MTM, or message client application) and the Message Server thread. Then it |
|
64 creates an instance of <codeph>CMsvSearchSortOperation</codeph> to perform |
|
65 the search-sort operation, and passes the session object into it. </p> <p>A |
|
66 search-sort query is created using <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> and |
|
67 is configured using various member functions of class <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita"><apiname>CMsvSearchSortQuery</apiname></xref> for |
|
68 instance whether to search for whole or partial words and the case sensitivity. </p> <p>The |
|
69 search and sort options are added to the query using <codeph>CMsvSearchSortQuery::AddSearchOptionL()</codeph> and <codeph>CMsvSearchSortQuery::AddSortOptionL()</codeph>. </p> <p>The search-sort operation is started by calling <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>, |
|
70 passing the query as a parameter. If no iterator parameter is specified, the |
|
71 search defaults to non-iterative. </p> <p>An instance of the <codeph>CMessAsyncWaiter</codeph> class |
|
72 is created for handling the asynchronous search request. This object is waited |
|
73 on until the Message Server completes the request. The results of the search |
|
74 are stored in an array using <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>. </p> <p>The |
|
75 result count is displayed by calling <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita#GUID-5D956759-5D21-3715-916E-F7E703172762/GUID-5E95F638-1252-3C63-A408-8FBAB445918D"><apiname>CMsvSearchSortOperation::GetResultCountL()</apiname></xref>. </p> <p>The |
|
76 query ID of the search is retrieved from the Message server, for later use, |
|
77 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> <p><b>Simple |
|
78 iterative search-sort</b> </p> <p>Iterative search-sort follows the same steps |
|
79 as described above, except that an iterator parameter is passed to the <codeph>RequestL()</codeph> function. |
|
80 To retrieve the results, <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita#GUID-5D956759-5D21-3715-916E-F7E703172762/GUID-3F38D82E-D350-3C80-8146-A339F1E189D8"><apiname>CMsvSearchSortOperation::GetNextResultL()</apiname></xref> is |
|
81 called in a <codeph>while</codeph> loop to retrieve one entry at a time. Iterative |
|
82 searching is useful when the client may not have enough memory to store an |
|
83 array of results. </p> <p><b>Combined search-sort</b> </p> <p>A combined search-sort |
|
84 is done by adding additional search options using <codeph>CMsvSearchSortQuery::AddSearchOptionL()</codeph>. </p> <p><b>Search-sort |
|
85 using a query ID</b> </p> <p>A query ID identifies a search-sort query. It |
|
86 is obtained by calling <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> following |
|
87 the completion of <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>. |
|
88 In this example, the query ID generated by the simple non-iterative search-sort |
|
89 is used to repeat the same search-sort. The overloaded <codeph>CMsvSearchSortOperation::RequestL()</codeph> function |
|
90 is used to initiate a search-sort operation with a query ID. </p> <p>After |
|
91 the request completes, a list of index entry ID objects (<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> depending |
|
92 on how the query was configured, using <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita#GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7/GUID-B040D6BA-670D-3CBF-B1F7-9AFD1F99267B"><apiname>CMsvSearchSortQuery::SetResultType()</apiname></xref>) |
|
93 is retrieved using <codeph>CMsvSearchSortOperation::GetResultsL()</codeph>. |
|
94 Finally the matching results are displayed in the console. </p> </section> |
|
95 <section id="GUID-AE5E0880-9CAB-57E5-83CB-196D487935DE"><title>Building and |
|
96 configuring</title> <p>To build the example: </p> <ul> |
|
97 <li id="GUID-61C94258-567F-575E-A75C-29D2165FC2CA"><p>You can build the example |
|
98 from your IDE or the command line. </p> <p>If you use an IDE, import the <filepath>bld.inf</filepath> file |
|
99 of the example into your IDE, and use the build command of the IDE. </p> <p>If |
|
100 you use the command line, open a command prompt, and set the current directory |
|
101 to the source code directory of the example. You can then build the example |
|
102 with the SBSv1 build tools with the following commands: </p> <p><userinput>bldmake |
|
103 bldfiles</userinput> </p> <p><userinput>abld build</userinput> </p> <p> <xref href="GUID-793A5EF9-CC16-5EEB-9011-6431EA76EB15.dita">How to use bldmake</xref> and <xref href="GUID-B6B54E07-3B34-5D5C-8815-93383FA8FB4B.dita">How to use abld</xref> describe |
|
104 how to use the SBSv1 build tools. </p> </li> |
|
105 <li id="GUID-F470E492-C920-58E0-860C-5CCE24B0C7F4"><p>For the emulator, the |
|
106 example builds an executable called <filepath>searchsortexample.exe</filepath> in |
|
107 the <filepath>epoc32\release\winscw\<udeb or urel>\</filepath> folder. </p> </li> |
|
108 </ul> </section> |
|
109 <section id="GUID-B72B706B-BB9F-5A0D-A36A-03135FE99E5C"><title>Running the |
|
110 example</title> <p> <filepath>searchsortexample.exe</filepath> takes user |
|
111 input from the console. The menu for the current example is as shown below: </p> <fig id="GUID-53020118-A1E3-56C3-AA81-9CED04533E27"> |
|
112 <image href="GUID-656E2E4F-D7C5-5FDC-B1E6-DFA5970BB3F0_d0e262349_href.jpg" placement="inline"/> |
|
113 </fig> <p>The user input is handled by <codeph>CKeyReader::RunL()</codeph>. </p> <p>For |
|
114 simple and combined non-iterative search-sort, the user provides the following |
|
115 inputs: 1) the text in the "To" field to search for, 2) whether case sensitivity |
|
116 is on of off, 3) whether whole word searching is on or off. </p> <p>The input |
|
117 values are saved in variables which are passed to the function <codeph>CSearchsortExample::SearchSortRequestWithoutIteratorL()</codeph>, |
|
118 and the settings are made accordingly. </p> <p>For the combined search-sort |
|
119 the 2nd and 3rd search options (size and subject) are hard coded. The iterative |
|
120 search-sort searches by size, which is also hard coded. </p> <p>To execute |
|
121 a search-sort using a query ID, <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> must |
|
122 first have been called because it generates the query ID. So, either option |
|
123 2 or 3 must have been called before option 5. </p> </section> |
|
124 <section><title>See also</title><p><xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita">Search-Sort |
|
125 Overview</xref></p></section> |
|
126 </refbody></reference> |