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

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-B007634D-4D55-528A-8B85-6120C633AC8B" xml:lang="en"><title>EUser

High Level Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The EUser High Level (EUserHL) library introduces a new L-Class idiom.

L-Classes have characteristics close to standard C++ value and handle classes,

including constructors, operators, and implicit operations may leave. </p>

<section><title>Purpose</title> <p>EUserHL introduces three APIs to improve

string handling, object creation and resource management. </p> </section>

<section><title>Intended Audience:</title> <p>This document is intended to

be used by Symbian platform licensees and application developers. </p> </section>

<section><title>EUserHL Library Details</title> <p>The DLL that provides the

functionality and the library to which your code must link is identified below. </p> <table id="GUID-35A8E4A4-E329-521E-8BE6-EE46B0B8C954">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry>DLL</entry>

<entry>LIB</entry>

<entry>Short Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <filepath>euserhl.dll</filepath>  </p> </entry>

<entry><p> <filepath>euserhl.lib</filepath>  </p> </entry>

<entry><p>The published interface for the EUserHL library. </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section><title>Functional Specification</title> <p>The EUserHL library is

a general purpose user library that provides a usability layer to hide away

some of the complexities of Symbian platform. </p> <p>The new <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> class

provides a self-managing, auto-extending wrapper around RBuf which removes

the need for the application developer to pre-declare the maximum length of

the descriptor. The class can be used as a local or member variable and is

automatically cleaned up when it goes out of scope. <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> provides

the essentially the same API as RBuf, but the RBuf methods that panic if the

descriptor runs out of space are replaced by leaving variants. These leaving

variants attempt to re-allocate the string buffer behind the scenes to make

room for the new data and leave if no memory can be allocated. </p> <p>The

template classes for automatic resource management allow application developers

to write robust code in fewer lines and hide away exception handling code.

Class templates are provided for automatically managing local and member variables

of pointer, reference, handle and generic types. The library provides the

ability for the application developer to define a clean up strategy of their

choosing to free managed resource when the managing object goes out of scope. </p> <p>The

new LString and automatic resource management classes introduce a new L-Class

idiom. The L prefix denotes that construction, copying, passing and returning

by value, assignment, and manipulation via operators should all be considered

potentially leaving operations unless otherwise explicitly documented. Code

that uses L-Classes should be written accordingly, in leave-safe style. </p> <p>The

new RAII concepts introduced through the LClass Idiom provide the means for

the safe handling of single phase construction. The automatic resource management

classes may be used as the basis for implementing leave-safe single-phase

construction, since fully initialized data members protected in this way will

get destroyed if their containing classes leave during execution of their

constructors. </p> </section>

<section><title>Architectural Relationship</title> <p>EUserHL provides three

technology areas, namely strings, automatic resource management, and single

phase construction. The class LString is derived from RBuf and HBufc is a

part of RBuf. </p> <p>EUserHL is a plugin to three <xref href="GUID-8919270A-B5CE-302D-B7CE-3A4680D5E8CF.dita"><apiname>EUser</apiname></xref> interfaces

including strings, which are instances or buffers, <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref>, <xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC</apiname></xref> and <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes</apiname></xref>. </p> <p><b>Description</b> </p> <p>EUserHL makes developing for Symbian platform easier by removing

some of the Symbianisms and making things like string handling, resource management

and error handling and object creation more familiar with standard C++ practices. </p> <p>EUserHL's

functionality is split into the following: </p> <ul>

<li id="GUID-74905CAF-AB9E-54CF-844A-27F5DF2FACA4"><p>Strings </p> </li>

<li id="GUID-311DEC6F-5258-5BE7-BCC1-54FEF4D74B9D"><p>Automatic Resource Management </p> </li>

<li id="GUID-B117718F-9556-5A4C-885C-DAF089CE7213"><p>Single Phase Construction </p> </li>

</ul> <p><b>Strings</b> </p> <p>The string handling classes provide self managing

resizable descriptors that are familiar to C++ developers. They provide a

std::string like interface. </p> <p>There are four variants of strings available: </p> <ul>

<li id="GUID-B9A77F84-3BAD-500D-BDFC-15428D5542DE"><p> <xref href="GUID-C5A68FFA-9AED-319D-B29D-723F9AA7FFD7.dita"><apiname>LString16</apiname></xref> is

derived from an <xref href="GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74.dita"><apiname>RBuf16</apiname></xref> and replaces the <xref href="GUID-9A863E0A-E588-367C-9444-C13AC0D44234.dita"><apiname>TText16</apiname></xref>. </p> </li>

<li id="GUID-D68149F2-A283-5500-80EF-508A1FAE0091"><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> is

a syntatical typedef of <xref href="GUID-C5A68FFA-9AED-319D-B29D-723F9AA7FFD7.dita"><apiname>LString16</apiname></xref>. </p> </li>

<li id="GUID-FACEC1E3-5EAF-52FA-A30F-99836F729719"><p> <xref href="GUID-C788743B-AD3C-3508-83CD-942EFA243B26.dita"><apiname>LString8</apiname></xref> is

derived from an <xref href="GUID-955061A8-A83E-39E5-8745-8FAC7DEA7BCC.dita"><apiname>RBuf8</apiname></xref> and replaces the <xref href="GUID-0DC8E9A8-8B5A-3566-B1C5-27B6E4F47F3C.dita"><apiname>TText8</apiname></xref>. </p> </li>

<li id="GUID-33A50E40-C955-5FB6-BD38-7317916B2D2B"><p> <xref href="GUID-1FF260A8-442C-34C6-A609-2A3E14EC1E19.dita"><apiname>LData</apiname></xref> is

a syntatical typedef of <xref href="GUID-C788743B-AD3C-3508-83CD-942EFA243B26.dita"><apiname>LString8</apiname></xref>. </p> </li>

</ul> <p><b>String Management</b> </p> <p>The following functions are provided

to manage these strings: </p> <ul>

<li id="GUID-A586D455-19D0-54EF-8E69-4C0EC09C8FBC"><p> <xref href="GUID-B7878C32-D093-3B15-A5B6-E91DA3A0961E.dita"><apiname>SetMaxLengthL()</apiname></xref> function

- To allocate an exact allocated size </p> <codeblock id="GUID-AFFCF3B0-0D8A-501F-831E-79EECA09853E" xml:space="preserve">s.SetMaxLengthL(2 * KMaxFileName);</codeblock> </li>

<li id="GUID-6DC23DC6-9A31-5D1E-B938-9E25568FFDA2"><p> <xref href="GUID-A3EE1898-D58C-3C15-8A98-7BEF85963AEB.dita"><apiname>ReserveFreeCapacityL()</apiname></xref> function

- To reserve extra free space in preparation for an operation that adds characters

to the string. </p> <codeblock id="GUID-008D9C13-D9AE-5D97-B97E-D96B5541603B" xml:space="preserve">s.ReserveFreeCapacityL(4);</codeblock> <p> </p> </li>

<li id="GUID-3E69FB9B-CAB9-507C-8EE5-5EF4D3D745F5"><p> <xref href="GUID-E016AEA6-D901-3AF4-AE52-CBE4308E962C.dita"><apiname> Compress()</apiname></xref> function

- To trade-off speed efficiency for space efficiency. </p> <codeblock id="GUID-C2EE7BC3-F9A1-5B56-8D25-C4021BE62876" xml:space="preserve">s.Compress();</codeblock> </li>

<li id="GUID-AEFBDD85-2E9C-5593-94D2-19A453587407"><p> <xref href="GUID-ABC0096D-A6DD-3AAA-8AA6-57474737983A.dita"><apiname>Reset()</apiname></xref> function

- To release the buffer used by the string without destroying the string itself. </p> <codeblock id="GUID-E7BF411C-9954-5160-A08E-1DF767DB6A79" xml:space="preserve">s.Reset();</codeblock> </li>

</ul> <p><b>Automatic Resource Management</b> </p> <p>Automatic resource management

improves on the Symbian platform memory management syntax by providing a number

of macros that hide the complexities of the clean-up stack. Once implemented,

it provides automatic, exception-safe clean-up when the object goes out of

scope. </p> <p>There are two variants of this simplified memory management

syntax: </p> <ul>

<li id="GUID-E1E27B21-9BBB-5703-93D2-D7150EB5C58F"><p> <b> LCleanedup</b> -

LCleanedup manages local variable clean-up routines. There are five LCleanedup

class templates. For more information, see <xref href="GUID-B007634D-4D55-528A-8B85-6120C633AC8B.dita#GUID-B007634D-4D55-528A-8B85-6120C633AC8B/GUID-760B7568-6A4D-5D6E-BC71-9651DF4F4E30">Key

EUserHL Classes</xref>  </p> </li>

<li id="GUID-8674C50E-B1B7-5A66-AC75-ABACDEDA08D2"><p> <b>LManaged </b> -

LManaged manages member variable clean-up routines. There are five LManaged

class templates. For more information, see <xref href="GUID-B007634D-4D55-528A-8B85-6120C633AC8B.dita#GUID-B007634D-4D55-528A-8B85-6120C633AC8B/GUID-760B7568-6A4D-5D6E-BC71-9651DF4F4E30">Key

EUserHL Classes</xref>  </p> </li>

</ul> <p><b>Single Phase Construction</b> </p> <p>Object initialisation is

simplified by single phase construction. Automatic resource management classes

allow the implementation of leave-safe single-phase construction. Fully initialised

data members are destroyed if their containing classes leave during constructor

execution. </p> <p>EUserHL provides the <xref href="GUID-8BB41BAD-5ED4-32E5-B4B4-312E472297CB.dita"><apiname>CONSTRUCTORS_MAY_LEAVE</apiname></xref> macro,

which is used to enable single phase construction. This macro provides memory

management capabilities for leaving constructors that would otherwise trigger

memory leaks. </p> <p><b>OR_LEAVE Macro</b> </p> <p>The OR_LEAVE macro is

a convenience macro that replaces <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-96AFAC46-F3AD-392B-8A97-AFCBF2978CFB"><apiname>User::LeaveIfError()</apiname></xref> function

and allows auxiliary error checking code to be deemphasized in most cases. </p> </section>

<section id="GUID-760B7568-6A4D-5D6E-BC71-9651DF4F4E30"><title>Key EUserHL

Classes</title> <p>The key classes that make up the EUserHL are as follows: </p> <table id="GUID-2F029AA2-1BBB-5426-AD94-1192D187B079">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p> <b>Classes</b>  </p> </entry>

<entry><p> <b> Description</b>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-33268411-26FD-39EF-9D21-A046023BFAE9.dita"><apiname>TClose</apiname></xref>  </p> </entry>

<entry><p>Calls the <xref href="GUID-01D2AF56-21E1-3FF3-BF86-0C356A1658EF.dita"><apiname>Close()</apiname></xref> member function of the managed

class </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-05EC3007-E3F2-3FA3-B07D-618EDC2EB55F.dita"><apiname>TRelease</apiname></xref>  </p> </entry>

<entry><p>Calls the <xref href="GUID-7F8FDB43-B847-3AFF-A78F-48F2E3DBFDC2.dita"><apiname>Release()</apiname></xref> member function of the managed

class. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-9E005556-76E5-306B-982C-B2C2BC268EB8.dita"><apiname>TDestroy</apiname></xref>  </p> </entry>

<entry><p>Calls the <xref href="GUID-38F49D2C-2798-37DB-82CC-A49EAB22B829.dita"><apiname>Destroy()</apiname></xref> member function of the managed

class. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-B5DB195A-C656-3BF6-8DCD-22AB6674B8F6.dita"><apiname>TFree</apiname></xref>  </p> </entry>

<entry><p>Calls the <xref href="GUID-14C80D6F-A201-397C-B3C1-642FEDC7C9DC.dita"><apiname>Free()</apiname></xref> member function of the managed

class. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-2455FD29-1396-38DE-B90D-F8099DCCA524.dita"><apiname>TResetAndDestroy</apiname></xref>  </p> </entry>

<entry><p>Calls the <xref href="GUID-AB4E9ABC-A09D-3974-8C1A-D7F7E9CBA2A6.dita"><apiname>ResetAndDestroy()</apiname></xref> member function of

the managed class. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-62F589DD-DFBB-3112-A9A7-D3943871E7AE.dita"><apiname>TPointerDelete</apiname></xref>  </p> </entry>

<entry><p>Deletes the managed pointer </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-5073F469-386E-3B06-BAD5-16A910D74BD9.dita"><apiname>TPointerFree</apiname></xref>  </p> </entry>

<entry><p>Calls <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-A1B58B92-E9B2-3C0F-89B3-BA3230A1E14F"><apiname>User::Free()</apiname></xref> with the managed pointer </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-428DE7ED-E76A-3A75-AA4D-185179A36D1E.dita"><apiname>TArrayDelete</apiname></xref>  </p> </entry>

<entry><p>Deallocates the array using array delete </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-166B7262-50A5-3C2E-B7DD-3291F96B31AA.dita"><apiname>LManagedPtr</apiname></xref>  </p> </entry>

<entry><p>Automatic memory management for pointers </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-2F473656-DD2D-33A7-8BC8-BA2C3337849C.dita"><apiname>LManagedRef</apiname></xref>  </p> </entry>

<entry><p>Automatic memory management for object references. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-FCBCB7A9-AF28-3591-A54D-8AF354E01D11.dita"><apiname>LManagedHandle</apiname></xref>  </p> </entry>

<entry><p>Automatic memory management for resource handles. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-B0B92876-6BE7-3B34-B19D-4B5E318F7BED.dita"><apiname>LManagedArray</apiname></xref>  </p> </entry>

<entry><p>Deletes the managed array. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-577F5B2D-0A1D-31AA-84EB-BE0B39F5A624.dita"><apiname>LManagedGuard</apiname></xref>  </p> </entry>

<entry><p>Generic automatic memory management </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-BD4E0CC4-75A2-306D-A860-06B4138F86EB.dita"><apiname>LCleanedupPtr</apiname></xref>  </p> </entry>

<entry><p>Automatic memory management for pointers. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-83938A18-23EF-301A-9D40-C89AEDB5DFF0.dita"><apiname>LCleanedupRef</apiname></xref>  </p> </entry>

<entry><p>Automatic memory management for object references. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-9ECEAE0C-3D5A-3B1F-88DD-28B37CE9950D.dita"><apiname>LCleanedupHandle</apiname></xref>  </p> </entry>

<entry><p>Automatic memory management for resource handles. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-A7B3BEBB-3805-3149-A9DB-075FFF3DED3F.dita"><apiname>LCleanedupArray</apiname></xref>  </p> </entry>

<entry><p>Automatic memory management for arrays. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-E6D04730-8064-3846-99E4-FB638C5EAA65.dita"><apiname>LCleanedupGuard</apiname></xref>  </p> </entry>

<entry><p>Generic automatic memory management </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section><title>Using EUserHL</title> <p>EUserHL may be used to: </p> <ul>

<li id="GUID-0BCE773E-470B-5C83-91EB-0A8B4EE31F66"><p><xref href="GUID-B419D99E-8312-5336-9693-3ED8DFCD0559.dita"> Automatic

Resource Management Tutorial</xref>  </p> </li>

<li id="GUID-1052381F-0F5C-511D-B11C-C65AFBBE03E3"><p><xref href="GUID-69D916D3-ED05-58DA-BA42-CE4D7E4F6482.dita">Automatic

Resource Management Class Templates Tutorial</xref>  </p> </li>

<li id="GUID-B0ED575A-01F1-5F81-A798-AC6978799901"><p><xref href="GUID-3799F0DA-B99C-55BB-B44F-63B971DF1865.dita"> Cleanup

Strategy Tutorial</xref>  </p> </li>

<li id="GUID-440F2390-D2BD-5803-9EC1-1FEAC03DA44C"><p><xref href="GUID-7984F8F7-DC7B-56E0-A5DA-071A3D87714A.dita">LString

Tutorial</xref> </p> </li>

<li id="GUID-AE5A4093-20C9-5182-9603-28ECE6634011"><p><xref href="GUID-5872329F-2B52-5F52-83C1-205F2F933877.dita">OR_LEAVE

macro Tutorial</xref>  </p> </li>

<li id="GUID-971A54D9-EA95-5669-A079-A09963D69FD7"><p><xref href="GUID-B9F07057-4B31-5FE8-BE4C-98CC8151CD29.dita">Single

Phase Constructor Tutorial</xref>  </p> </li>

</ul> </section>

<section><title>See Also</title> <p><xref href="GUID-ECE93783-F571-51DA-AB92-EDDA8618A85C.dita">EUser

High Level Library Concepts</xref>  </p> <p><xref href="GUID-D33EB877-CCCB-527B-8AFC-4A8385C55E78.dita">EUser

High Level Library Tutorials</xref>  </p> </section>