EUserHlExample: EUser High Level example

This example demonstrates how to use the EUser High Level library and includes the ceratian features supported by the library. It also demonstrates the usage of specific APIs associated with the EUser High Level Library.

Purpose

This example demonstrates the following features of EUserHL:

  • String handling

  • Object creation and automatic resource management

  • Memory usage by EUserHL classes

Download

Click on the following link to download the example: EUserHlExample.zip

Click: browse to view the example code.

Design and implementation

The example implements three main functions:

  • WalkthroughStringsL() demonstrates string handling.

  • WalkthroughManagedL() demonstrates object creation and resource management.

  • WalkthroughUsageL() demonstrates memory usage by EUserHL library classes.

String handling

LString is designed to be a self-managing, resizable alternative to some of the existing descriptor types.

WalkthroughStringsL() demonstrates how LString can be used in similar ways to the existing TDesC and TDes descriptor classes, as well as showing some additional functions, including:

  • LString::SetMaxlengthL()

  • LString::ReserveFreeCapacityL()

  • LString::Compress()

  • LString::Reset()

CStringUserTwoPhase is used to demonstrate the use of LString s in the two-phase construction pattern. LCleanedupPtr is used in place of the CleanupStack in the NewL() function.

CStringUserSinglePhase is used to demonstrate the use of LString s in the single phase construction pattern. A macro CONSTRUCTORS_MAY_LEAVE is declared to ensure cleanup is correctly handled if the constructor leaves.

Object creation and automatic resource management

The LCleanedUpXxx classes LCleanedupPtr , LCleanedupHandle , LCleanedupArray , LCleanedupGuard and LCleanedupRef classes provide automatic resource management that avoids the need for the programmer to use the cleanup stack.

WalkthroughManagedL() shows how the various LCleanedUpXxx classes are used. It shows how objects declared locally to a function (a pointer, a resource handle, an array, and an object cleaned up using a TCleanupItem ) are deleted automatically when they go out of scope.

CManagedUserTwoPhase demonstrates the use of the management classes in the two-phase construction pattern. LCleanedupPtr is used in the NewL() function in place of the CleanupStack . LManagedXxx classes (for example LManagedPtr and LManagedHandle ) are used to handle cleanup of member data.

Related APIs

CleanupStack

LCleanedupArray

LCleanedupGuard

LCleanedupHandle

LCleanedupPtr

LCleanedupRef

LManagedHandle

LManagedPtr

TCleanupItem

Memory usage

WalkthroughUsageL() API demonstrates the memory overhead of using EUserHL.

Building and configuring

To build the example:

  • You can build the example from your IDE or the command line.

    If you use an IDE, import the bld.inf file of the example into your IDE, and use the build command of the IDE.

    If you use the command line, open a command prompt, and set the current directory to the source code directory of the example. You can then build the example with the SBSv1 build tools with the following commands:

    bldmake bldfiles

    abld build

  • For the emulator, the example builds an executable called euserhlexample.exe in the epoc32\release\winscw\<udeb or urel>\ folder.

Running the example

This is a console application. The user presses any key to step through it and the emulator closes down on exit.