--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-B007634D-4D55-528A-8B85-6120C633AC8B.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,230 @@
+<?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>
\ No newline at end of file