|
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-E26E46AE-914E-5F21-AB44-10F926BAA8AC" xml:lang="en"><title>EUserHlExample: |
|
13 EUser High Level example</title><shortdesc>This example demonstrates how to use the EUser High Level library |
|
14 and includes the ceratian features supported by the library. It also demonstrates |
|
15 the usage of specific APIs associated with the EUser High Level Library. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody> |
|
16 <section id="GUID-EB6346F5-1C3C-5DEB-AD3A-36474C372E1C"><title>Purpose</title> <p>This |
|
17 example demonstrates the following features of EUserHL: </p> <ul> |
|
18 <li id="GUID-31A8E1A2-F2A9-5DDB-A880-FF27A41F1C3B"><p>String handling </p> </li> |
|
19 <li id="GUID-C09DC120-E1B8-5F60-9E90-2078E122C8EF"><p>Object creation and |
|
20 automatic resource management </p> </li> |
|
21 <li id="GUID-D7F1F68F-B9FC-524C-8B3B-D987582AEE76"><p>Memory usage by EUserHL |
|
22 classes </p> </li> |
|
23 </ul> </section> |
|
24 <section id="GUID-4BE93C59-6FBA-5F1B-90AE-1A8D30FB084C"><title>Download</title> <p>Click |
|
25 on the following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-66d31721-b6a6-4c84-b51d-c92f3927df4c.zip" scope="external">EUserHlExample.zip</xref></p><p>Click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-66d31721-b6a6-4c84-b51d-c92f3927df4c.html" scope="peer">browse</xref> to view the example code. </p> </section> |
|
26 <section id="GUID-62A4FC58-6832-5282-9E14-DCAB88913E8F"><title>Design and |
|
27 implementation</title> <p>The example implements three main functions: </p> <ul> |
|
28 <li id="GUID-5B20BDEE-B5A1-5D07-A19A-5CA298D1CEAA"><p> <codeph>WalkthroughStringsL()</codeph> demonstrates |
|
29 string handling. </p> </li> |
|
30 <li id="GUID-FC833C89-5A32-52E6-93D3-F45DC0A7E865"><p> <codeph>WalkthroughManagedL()</codeph> demonstrates |
|
31 object creation and resource management. </p> </li> |
|
32 <li id="GUID-7914F607-47BC-557A-B7F4-1432A294F743"><p> <codeph>WalkthroughUsageL()</codeph> demonstrates |
|
33 memory usage by EUserHL library classes. </p> </li> |
|
34 </ul> <p><b>String handling</b> </p> <p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> is designed |
|
35 to be a self-managing, resizable alternative to some of the existing descriptor |
|
36 types. </p> <p> <codeph>WalkthroughStringsL()</codeph> demonstrates how <codeph>LString</codeph> can |
|
37 be used in similar ways to the existing <codeph>TDesC</codeph> and <codeph>TDes</codeph> descriptor |
|
38 classes, as well as showing some additional functions, including: </p> <ul> |
|
39 <li id="GUID-DA576055-E813-51DE-8232-9E961596E34D"><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita#GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC/GUID-3A7A28FA-6647-3F51-A628-7857898E5090"><apiname>LString::SetMaxlengthL()</apiname></xref> </p> </li> |
|
40 <li id="GUID-7A845FEC-A1B6-592F-A4E4-B93F301E3E1A"><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita#GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC/GUID-D7071D5E-E3EA-35ED-9A8F-D330162493A7"><apiname>LString::ReserveFreeCapacityL()</apiname></xref> </p> </li> |
|
41 <li id="GUID-3883BD67-A7AA-5E55-8281-D41BC5871815"><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita#GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC/GUID-48151B50-C8C4-3011-9A76-8242EB7E1DDC"><apiname>LString::Compress()</apiname></xref> </p> </li> |
|
42 <li id="GUID-F7BC1D06-38E9-582A-870F-CE38A6DC4FD5"><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita#GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC/GUID-7A5C522F-9B29-3443-A853-EF06BAD08352"><apiname>LString::Reset()</apiname></xref> </p> </li> |
|
43 </ul> <p> <codeph>CStringUserTwoPhase</codeph> is used to demonstrate the |
|
44 use of <codeph>LString</codeph> s in the two-phase construction pattern. <xref href="GUID-BD4E0CC4-75A2-306D-A860-06B4138F86EB.dita"><apiname>LCleanedupPtr</apiname></xref> is |
|
45 used in place of the <xref href="GUID-0DD554D7-B9B1-3FD3-898F-4D855144FCEA.dita"><apiname>CleanupStack</apiname></xref> in the <codeph>NewL()</codeph> function. </p> <p> <codeph>CStringUserSinglePhase</codeph> is |
|
46 used to demonstrate the use of <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> s in the single |
|
47 phase construction pattern. A macro <codeph>CONSTRUCTORS_MAY_LEAVE</codeph> is |
|
48 declared to ensure cleanup is correctly handled if the constructor leaves. </p> <p><b>Object |
|
49 creation and automatic resource management</b> </p> <p>The <codeph>LCleanedUpXxx</codeph> classes <xref href="GUID-BD4E0CC4-75A2-306D-A860-06B4138F86EB.dita"><apiname>LCleanedupPtr</apiname></xref>, <xref href="GUID-9ECEAE0C-3D5A-3B1F-88DD-28B37CE9950D.dita"><apiname>LCleanedupHandle</apiname></xref>, <xref href="GUID-A7B3BEBB-3805-3149-A9DB-075FFF3DED3F.dita"><apiname>LCleanedupArray</apiname></xref>, <xref href="GUID-E6D04730-8064-3846-99E4-FB638C5EAA65.dita"><apiname>LCleanedupGuard</apiname></xref> and <xref href="GUID-83938A18-23EF-301A-9D40-C89AEDB5DFF0.dita"><apiname>LCleanedupRef</apiname></xref> classes |
|
50 provide automatic resource management that avoids the need for the programmer |
|
51 to use the cleanup stack. </p> <p> <codeph>WalkthroughManagedL()</codeph> shows |
|
52 how the various <codeph>LCleanedUpXxx</codeph> classes are used. It shows |
|
53 how objects declared locally to a function (a pointer, a resource handle, |
|
54 an array, and an object cleaned up using a <xref href="GUID-CD0A798E-7E42-3689-8E86-F5FD43C758FC.dita"><apiname>TCleanupItem</apiname></xref>) |
|
55 are deleted automatically when they go out of scope. </p> <p> <codeph>CManagedUserTwoPhase</codeph> demonstrates |
|
56 the use of the management classes in the two-phase construction pattern. <xref href="GUID-BD4E0CC4-75A2-306D-A860-06B4138F86EB.dita"><apiname>LCleanedupPtr</apiname></xref> is |
|
57 used in the <codeph>NewL()</codeph> function in place of the <xref href="GUID-0DD554D7-B9B1-3FD3-898F-4D855144FCEA.dita"><apiname>CleanupStack</apiname></xref>. <codeph>LManagedXxx</codeph> classes |
|
58 (for example <xref href="GUID-166B7262-50A5-3C2E-B7DD-3291F96B31AA.dita"><apiname>LManagedPtr</apiname></xref> and <xref href="GUID-FCBCB7A9-AF28-3591-A54D-8AF354E01D11.dita"><apiname>LManagedHandle</apiname></xref>) |
|
59 are used to handle cleanup of member data. </p> <p><b>Related APIs</b></p><p><xref href="GUID-0DD554D7-B9B1-3FD3-898F-4D855144FCEA.dita"><apiname>CleanupStack</apiname></xref></p><p><xref href="GUID-A7B3BEBB-3805-3149-A9DB-075FFF3DED3F.dita"><apiname>LCleanedupArray</apiname></xref></p><p><xref href="GUID-E6D04730-8064-3846-99E4-FB638C5EAA65.dita"><apiname>LCleanedupGuard</apiname></xref></p><p><xref href="GUID-9ECEAE0C-3D5A-3B1F-88DD-28B37CE9950D.dita"><apiname>LCleanedupHandle</apiname></xref></p><p><xref href="GUID-BD4E0CC4-75A2-306D-A860-06B4138F86EB.dita"><apiname>LCleanedupPtr</apiname></xref></p><p><xref href="GUID-83938A18-23EF-301A-9D40-C89AEDB5DFF0.dita"><apiname>LCleanedupRef</apiname></xref></p><p><xref href="GUID-FCBCB7A9-AF28-3591-A54D-8AF354E01D11.dita"><apiname>LManagedHandle</apiname></xref></p><p><xref href="GUID-166B7262-50A5-3C2E-B7DD-3291F96B31AA.dita"><apiname>LManagedPtr</apiname></xref></p><p><xref href="GUID-CD0A798E-7E42-3689-8E86-F5FD43C758FC.dita"><apiname>TCleanupItem</apiname></xref></p><p><b>Memory |
|
60 usage</b> </p> <p> <codeph>WalkthroughUsageL()</codeph> API demonstrates the |
|
61 memory overhead of using EUserHL. </p> </section> |
|
62 <section id="GUID-1BB8D12F-2303-5F46-BF3F-78416EAB2DBE"><title>Building and |
|
63 configuring</title> <p>To build the example: </p> <ul> |
|
64 <li id="GUID-324858E0-CD22-533E-A291-4CD4C88935BC"><p>You can build the example |
|
65 from your IDE or the command line. </p> <p>If you use an IDE, import the <filepath>bld.inf</filepath> file |
|
66 of the example into your IDE, and use the build command of the IDE. </p> <p>If |
|
67 you use the command line, open a command prompt, and set the current directory |
|
68 to the source code directory of the example. You can then build the example |
|
69 with the SBSv1 build tools with the following commands: </p> <p><userinput>bldmake |
|
70 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 |
|
71 how to use the SBSv1 build tools. </p> </li> |
|
72 <li id="GUID-01951689-451E-5B11-8A71-08B263B4CA8A"><p>For the emulator, the |
|
73 example builds an executable called <filepath>euserhlexample.exe</filepath> in |
|
74 the <filepath>epoc32\release\winscw\<udeb or urel>\</filepath> folder. </p> </li> |
|
75 </ul> </section> |
|
76 <section id="GUID-B4B61C60-2DAF-5279-A934-DF5B5FCA29E7"><title>Running the |
|
77 example</title> <p>This is a console application. The user presses any key |
|
78 to step through it and the emulator closes down on exit. </p> </section> |
|
79 <section><title>See also:</title><p><xref href="GUID-B007634D-4D55-528A-8B85-6120C633AC8B.dita">EUser |
|
80 High Level Library</xref></p></section> |
|
81 </refbody></reference> |