<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE reference
  PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="GUID-E26E46AE-914E-5F21-AB44-10F926BAA8AC" xml:lang="en"><title>EUserHlExample:
EUser High Level example</title><shortdesc>This example demonstrates how to use the EUser High Level library
and includes the ceratian features supported by the library. It also demonstrates
the usage of specific APIs associated with the EUser High Level Library. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody>
<section id="GUID-EB6346F5-1C3C-5DEB-AD3A-36474C372E1C"><title>Purpose</title> <p>This
example demonstrates the following features of EUserHL: </p> <ul>
<li id="GUID-31A8E1A2-F2A9-5DDB-A880-FF27A41F1C3B"><p>String handling </p> </li>
<li id="GUID-C09DC120-E1B8-5F60-9E90-2078E122C8EF"><p>Object creation and
automatic resource management </p> </li>
<li id="GUID-D7F1F68F-B9FC-524C-8B3B-D987582AEE76"><p>Memory usage by EUserHL
classes </p> </li>
</ul> </section>
<section id="GUID-4BE93C59-6FBA-5F1B-90AE-1A8D30FB084C"><title>Download</title> <p>Click
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>
<section id="GUID-62A4FC58-6832-5282-9E14-DCAB88913E8F"><title>Design and
implementation</title> <p>The example implements three main functions: </p> <ul>
<li id="GUID-5B20BDEE-B5A1-5D07-A19A-5CA298D1CEAA"><p> <codeph>WalkthroughStringsL()</codeph> demonstrates
string handling. </p> </li>
<li id="GUID-FC833C89-5A32-52E6-93D3-F45DC0A7E865"><p> <codeph>WalkthroughManagedL()</codeph> demonstrates
object creation and resource management. </p> </li>
<li id="GUID-7914F607-47BC-557A-B7F4-1432A294F743"><p> <codeph>WalkthroughUsageL()</codeph> demonstrates
memory usage by EUserHL library classes. </p> </li>
</ul> <p><b>String handling</b> </p> <p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> is designed
to be a self-managing, resizable alternative to some of the existing descriptor
types. </p> <p> <codeph>WalkthroughStringsL()</codeph> demonstrates how <codeph>LString</codeph> can
be used in similar ways to the existing <codeph>TDesC</codeph> and <codeph>TDes</codeph> descriptor
classes, as well as showing some additional functions, including: </p> <ul>
<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>
<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>
<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>
<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>
</ul> <p> <codeph>CStringUserTwoPhase</codeph> is used to demonstrate the
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
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
used to demonstrate the use of <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> s in the single
phase construction pattern. A macro <codeph>CONSTRUCTORS_MAY_LEAVE</codeph> is
declared to ensure cleanup is correctly handled if the constructor leaves. </p> <p><b>Object
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
provide automatic resource management that avoids the need for the programmer
to use the cleanup stack. </p> <p> <codeph>WalkthroughManagedL()</codeph> shows
how the various <codeph>LCleanedUpXxx</codeph> classes are used. It shows
how objects declared locally to a function (a pointer, a resource handle,
an array, and an object cleaned up using a <xref href="GUID-CD0A798E-7E42-3689-8E86-F5FD43C758FC.dita"><apiname>TCleanupItem</apiname></xref>)
are deleted automatically when they go out of scope. </p> <p> <codeph>CManagedUserTwoPhase</codeph> demonstrates
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
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
(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>)
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
usage</b> </p> <p> <codeph>WalkthroughUsageL()</codeph> API demonstrates the
memory overhead of using EUserHL. </p> </section>
<section id="GUID-1BB8D12F-2303-5F46-BF3F-78416EAB2DBE"><title>Building and
configuring</title> <p>To build the example: </p> <ul>
<li id="GUID-324858E0-CD22-533E-A291-4CD4C88935BC"><p>You can build the example
from your IDE or the command line. </p> <p>If you use an IDE, import the <filepath>bld.inf</filepath> file
of the example into your IDE, and use the build command of the IDE. </p> <p>If
you use the command line, open a command prompt, and set the current directory
to the source code directory of the example. You can then build the example
with the SBSv1 build tools with the following commands: </p> <p><userinput>bldmake
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
how to use the SBSv1 build tools. </p> </li>
<li id="GUID-01951689-451E-5B11-8A71-08B263B4CA8A"><p>For the emulator, the
example builds an executable called <filepath>euserhlexample.exe</filepath> in
the <filepath>epoc32\release\winscw\&lt;udeb or                 urel&gt;\</filepath> folder. </p> </li>
</ul> </section>
<section id="GUID-B4B61C60-2DAF-5279-A934-DF5B5FCA29E7"><title>Running the
example</title> <p>This is a console application. The user presses any key
to step through it and the emulator closes down on exit. </p> </section>
<section><title>See also:</title><p><xref href="GUID-B007634D-4D55-528A-8B85-6120C633AC8B.dita">EUser
High Level Library</xref></p></section>
</refbody></reference>