1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

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

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

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

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

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

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

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

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

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

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

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

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

    24 <thead>

    25 <row>

    26 <entry>DLL</entry>

    27 <entry>LIB</entry>

    28 <entry>Short Description</entry>

    29 </row>

    30 </thead>

    31 <tbody>

    32 <row>

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

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

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

    36 </row>

    37 </tbody>

    38 </tgroup>

    39 </table> </section>

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

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

    42 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

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

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

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

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

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

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

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

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

    51 template classes for automatic resource management allow application developers

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

    53 Class templates are provided for automatically managing local and member variables

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

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

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

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

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

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

    60 potentially leaving operations unless otherwise explicitly documented. Code

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

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

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

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

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

    66 get destroyed if their containing classes leave during execution of their

    67 constructors. </p> </section>

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

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

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

    71 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

    72 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   106 syntax: </p> <ul>

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

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

   109 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

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

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

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

   113 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

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

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

   116 simplified by single phase construction. Automatic resource management classes

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

   118 data members are destroyed if their containing classes leave during constructor

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

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

   121 management capabilities for leaving constructors that would otherwise trigger

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

   123 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

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

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

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

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

   128 <tbody>

   129 <row>

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

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

   132 </row>

   133 <row>

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

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

   136 class </p> </entry>

   137 </row>

   138 <row>

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

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

   141 class. </p> </entry>

   142 </row>

   143 <row>

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

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

   146 class. </p> </entry>

   147 </row>

   148 <row>

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

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

   151 class. </p> </entry>

   152 </row>

   153 <row>

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

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

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

   157 </row>

   158 <row>

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

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

   161 </row>

   162 <row>

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

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

   165 </row>

   166 <row>

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

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

   169 </row>

   170 <row>

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

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

   173 </row>

   174 <row>

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

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

   177 </row>

   178 <row>

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

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

   181 </row>

   182 <row>

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

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

   185 </row>

   186 <row>

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

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

   189 </row>

   190 <row>

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

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

   193 </row>

   194 <row>

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

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

   197 </row>

   198 <row>

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

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

   201 </row>

   202 <row>

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

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

   205 </row>

   206 <row>

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

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

   209 </row>

   210 </tbody>

   211 </tgroup>

   212 </table> </section>

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

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

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

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

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

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

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

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

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

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

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

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

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

   226 </ul> </section>

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

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

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

   230 </conbody></concept>