<?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 id="GUID-3832C7E4-6930-474C-B98E-AB601C70455E"><title>Purpose</title> <p>EUserHL introduces three APIs to improve
string handling, object creation and resource management. </p> </section>
<section id="GUID-20EC6FD1-D23F-4936-8004-6B04ACBD34F0"><title>Intended Audience:</title> <p>This document is intended to
be used by the Symbian platform licensees and application developers. </p> </section>
<section id="GUID-A9757824-28F9-4901-B9E7-BCDBAF954E70"><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 id="GUID-2F4E7D4D-B1BC-4BAC-A616-76A7F6140D0D"><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 the 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 id="GUID-290FDAFB-8C32-44B8-B071-110F69FB0B9E"><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 the 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 id="GUID-D0295359-BE09-4F45-BA24-50892163B41B"><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 id="GUID-50B67735-3DA3-4740-9A1B-070FF76CD087"><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>
</conbody></concept>