EUser High Level Overview

Purpose

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

Intended Audience:

This document is intended to be used by the 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.

Functional Specification

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.

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

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:

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