<?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> </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 id="GUID-4D11EB1C-F2C4-4B0F-8DFC-3ECB15141A20"><title>See also:</title><p><xref href="GUID-B007634D-4D55-528A-8B85-6120C633AC8B.dita">EUser High Level

Library</xref></p></section>