EUser -High Level Overview

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.

Purpose

EUserHL introduces three APIs to improve -string handling, object creation and resource management.

Intended Audience:

This document is intended to -be used by Symbian platform licensees and application developers.

EUserHL Library Details

The DLL that provides the -functionality and the library to which your code must link is identified below.

- - - -DLL -LIB -Short Description - - - - -

euserhl.dll

euserhl.lib

The published interface for the EUserHL library.

- - - -

Functional Specification

The EUserHL library is -a general purpose user library that provides a usability layer to hide away -some of the complexities of Symbian platform.

The new LString 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. LString 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.

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.

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.

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.

Architectural Relationship

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.

EUserHL is a plugin to three EUser interfaces -including strings, which are instances or buffers, RBuf, HBufC and TDes.

Description

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.

EUserHL's -functionality is split into the following:

Strings
Automatic Resource Management
Single Phase Construction

Strings

The string handling classes provide self managing -resizable descriptors that are familiar to C++ developers. They provide a -std::string like interface.

There are four variants of strings available:

LString16 is -derived from an RBuf16 and replaces the TText16.
LString is -a syntatical typedef of LString16.
LString8 is -derived from an RBuf8 and replaces the TText8.
LData is -a syntatical typedef of LString8.

String Management

The following functions are provided -to manage these strings:

SetMaxLengthL() function -- To allocate an exact allocated size
s.SetMaxLengthL(2 * KMaxFileName);
ReserveFreeCapacityL() function -- To reserve extra free space in preparation for an operation that adds characters -to the string.
s.ReserveFreeCapacityL(4);
Compress() function -- To trade-off speed efficiency for space efficiency.
s.Compress();
Reset() function -- To release the buffer used by the string without destroying the string itself.
s.Reset();

Automatic Resource Management

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.

There are two variants of this simplified memory management -syntax:

LCleanedup - -LCleanedup manages local variable clean-up routines. There are five LCleanedup -class templates. For more information, see Key -EUserHL Classes
LManaged - -LManaged manages member variable clean-up routines. There are five LManaged -class templates. For more information, see Key -EUserHL Classes

Single Phase Construction

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.

EUserHL provides the CONSTRUCTORS_MAY_LEAVE macro, -which is used to enable single phase construction. This macro provides memory -management capabilities for leaving constructors that would otherwise trigger -memory leaks.

OR_LEAVE Macro

The OR_LEAVE macro is -a convenience macro that replaces User::LeaveIfError() function -and allows auxiliary error checking code to be deemphasized in most cases.

Key EUserHL -Classes

The key classes that make up the EUserHL are as follows:

- - - -

Classes

Description

- - -

TClose

Calls the Close() member function of the managed -class

- - -

TRelease

Calls the Release() member function of the managed -class.

- - -

TDestroy

Calls the Destroy() member function of the managed -class.

- - -

TFree

Calls the Free() member function of the managed -class.

- - -

TResetAndDestroy

Calls the ResetAndDestroy() member function of -the managed class.

- - -

TPointerDelete

Deletes the managed pointer

- - -

TPointerFree

Calls User::Free() with the managed pointer

- - -

TArrayDelete

Deallocates the array using array delete

- - -

LManagedPtr

Automatic memory management for pointers

- - -

LManagedRef

Automatic memory management for object references.

- - -

LManagedHandle

Automatic memory management for resource handles.

- - -

LManagedArray

Deletes the managed array.

- - -

LManagedGuard

Generic automatic memory management

- - -

LCleanedupPtr

Automatic memory management for pointers.

- - -

LCleanedupRef

Automatic memory management for object references.

- - -

LCleanedupHandle

Automatic memory management for resource handles.

- - -

LCleanedupArray

Automatic memory management for arrays.

- - -

LCleanedupGuard

Generic automatic memory management

- - - -

Using EUserHL

EUserHL may be used to:

Automatic -Resource Management Tutorial
Automatic -Resource Management Class Templates Tutorial
Cleanup -Strategy Tutorial
LString -Tutorial
OR_LEAVE -macro Tutorial
Single -Phase Constructor Tutorial

See Also

EUser -High Level Library Concepts

EUser -High Level Library Tutorials

+ + + + + +EUser +High Level Overview +

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.

Purpose

EUserHL introduces three APIs to improve +string handling, object creation and resource management.

Intended Audience:

This document is intended to +be used by Symbian platform licensees and application developers.

EUserHL Library Details

The DLL that provides the +functionality and the library to which your code must link is identified below.

+ + + +DLL +LIB +Short Description + + + + +

euserhl.dll

euserhl.lib

The published interface for the EUserHL library.

+ + + +

Functional Specification

The EUserHL library is +a general purpose user library that provides a usability layer to hide away +some of the complexities of Symbian platform.

The new LString 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. LString 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.

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.

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.

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.

Architectural Relationship

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.

EUserHL is a plugin to three EUser interfaces +including strings, which are instances or buffers, RBuf, HBufC and TDes.

Description

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.

EUserHL's +functionality is split into the following:

Strings
Automatic Resource Management
Single Phase Construction

Strings

The string handling classes provide self managing +resizable descriptors that are familiar to C++ developers. They provide a +std::string like interface.

There are four variants of strings available:

LString16 is +derived from an RBuf16 and replaces the TText16.
LString is +a syntatical typedef of LString16.
LString8 is +derived from an RBuf8 and replaces the TText8.
LData is +a syntatical typedef of LString8.

String Management

The following functions are provided +to manage these strings:

SetMaxLengthL() function +- To allocate an exact allocated size
s.SetMaxLengthL(2 * KMaxFileName);
ReserveFreeCapacityL() function +- To reserve extra free space in preparation for an operation that adds characters +to the string.
s.ReserveFreeCapacityL(4);
Compress() function +- To trade-off speed efficiency for space efficiency.
s.Compress();
Reset() function +- To release the buffer used by the string without destroying the string itself.
s.Reset();

Automatic Resource Management

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.

There are two variants of this simplified memory management +syntax:

LCleanedup - +LCleanedup manages local variable clean-up routines. There are five LCleanedup +class templates. For more information, see Key +EUserHL Classes
LManaged - +LManaged manages member variable clean-up routines. There are five LManaged +class templates. For more information, see Key +EUserHL Classes

Single Phase Construction

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.

EUserHL provides the CONSTRUCTORS_MAY_LEAVE macro, +which is used to enable single phase construction. This macro provides memory +management capabilities for leaving constructors that would otherwise trigger +memory leaks.

OR_LEAVE Macro

The OR_LEAVE macro is +a convenience macro that replaces User::LeaveIfError() function +and allows auxiliary error checking code to be deemphasized in most cases.

Key EUserHL +Classes

The key classes that make up the EUserHL are as follows:

+ + + +

Classes

Description

+ + +

TClose

Calls the Close() member function of the managed +class

+ + +

TRelease

Calls the Release() member function of the managed +class.

+ + +

TDestroy

Calls the Destroy() member function of the managed +class.

+ + +

TFree

Calls the Free() member function of the managed +class.

+ + +

TResetAndDestroy

Calls the ResetAndDestroy() member function of +the managed class.

+ + +

TPointerDelete

Deletes the managed pointer

+ + +

TPointerFree

Calls User::Free() with the managed pointer

+ + +

TArrayDelete

Deallocates the array using array delete

+ + +

LManagedPtr

Automatic memory management for pointers

+ + +

LManagedRef

Automatic memory management for object references.

+ + +

LManagedHandle

Automatic memory management for resource handles.

+ + +

LManagedArray

Deletes the managed array.

+ + +

LManagedGuard

Generic automatic memory management

+ + +

LCleanedupPtr

Automatic memory management for pointers.

+ + +

LCleanedupRef

Automatic memory management for object references.

+ + +

LCleanedupHandle

Automatic memory management for resource handles.

+ + +

LCleanedupArray

Automatic memory management for arrays.

+ + +

LCleanedupGuard

Generic automatic memory management

+ + + +

Using EUserHL

EUserHL may be used to:

Automatic +Resource Management Tutorial
Automatic +Resource Management Class Templates Tutorial
Cleanup +Strategy Tutorial
LString +Tutorial
OR_LEAVE +macro Tutorial
Single +Phase Constructor Tutorial