<?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>