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

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

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