examples/SysLibs/EUserHLExample/src/euserhlexample.cpp

/*
Copyright (c) 2008-2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this
  list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.
* Neither the name of Nokia Corporation nor the names of its contributors
  may be used to endorse or promote products derived from this software
  without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Description:  
*/


#include <f32file.h>
#include <e32cons.h>
#include <euserhl.h>


_LIT(KTxtExample,"EUsableExample\n");
_LIT(KTxtPressAnyKeyToContinue,"Press any key to continue\n");

CConsoleBase* gConsole;

_LIT(KPath, "c:\\a\\b\\c");
_LIT(KOne, "One ");
_LIT(KTwo, "Two ");
_LIT(KTesting, "Testing ");

void MaybeLeave()
        {
        // Some code that may leave
        }

HBufC* AllocateNameL(const TDesC& aDes)
        {
        return aDes.AllocL();
        }

void GetCurrentPath(TDes& aDes)
        {
        aDes = KPath;
        }

void GetCurrentPathString(LString& aString)
        {
        aString = KPath; // Will auto-grow if necessary, may leave
        }

LString AppendCurrentPathStringL(LString aString)
        {
        /*
        This method accepts and returns LStrings by value. It works but
        is not recommended due to the inherent inefficiencies.
        */
        LString result(aString);
        result += KPath;
        return result;
        }

class CTicker : public CBase
        {
public:
        void Tick() { ++iTicks; }
        void Tock() { ++iTocks; }

        void Zap() { delete this; }

public:
        TInt iTicks;
        TInt iTocks;
        };

// Defines a custom pointer cleanup policy that calls the Zap member
class TTickerZapStrategy
        {
public:
        static void Cleanup(CTicker* aPtr)
                {
                /*
                The general template/class scaffolding remains the same
                for all custom cleanups, just this cleanup body varies
                */
                aPtr->Zap();
                _LIT(KTxtPrintZapp, "Zapped CTicker\n");
                gConsole->Printf(KTxtPrintZapp);
                }
        };

void RegisterTicker(CTicker& aTicker)
        {
        (void)aTicker;
        }

void RegisterTickerPtr(CTicker* aTicker)
        {
        (void)aTicker;
        }

void TakeTickerOwnership(CTicker* aTicker)
        {
        delete aTicker;
        }

void RegisterTimer(RTimer& aTimer)
        {
        (void)aTimer;
        }

// Defines a custom handle cleanup policy that calls Cancel() then Close()
class TCancelClose
        {
public:
        template <class T>
        static void Cleanup(T* aHandle)
                {
                /*
                The general template/class scaffolding remains the same
                for all custom cleanups, just this cleanup body varies
                */
                aHandle->Cancel();
                aHandle->Close();
                _LIT(KTxtCancel,"Cancel Closed RTimer\n");
                gConsole->Printf(KTxtCancel);
                }
        };

void BespokeCleanupFunction(TAny* /*aData*/)
        {
        _LIT(KTxtCleanup,"BespokeCleanupFunction\n");
        gConsole->Printf(KTxtCleanup);
        }

// The walkthroughs themselves

class CStringUserTwoPhase : public CBase
        {
public:
        static CStringUserTwoPhase* NewL(const TDesC& aName)
                {
                /*
                We can use the resource management utility classes in
                two-phase if we want.
                */
                LCleanedupPtr<CStringUserTwoPhase> self(new(ELeave) CStringUserTwoPhase);
                self->Construct(aName);
                /*
                Calling Unmanage() disables cleanup and yields the
                previously managed pointer so that it can be safely
                returned
                */
                return self.Unmanage(); 
                }

        virtual void Construct(const TDesC& aName)
                {
                /*
                This assignment may leave if LString fails to allocate a
                heap buffer large enough to hold the data in aName
                */
                iName = aName; 
                }

        ~CStringUserTwoPhase()
                {
                // The iName LString cleans up after itself automatically 
                }

        const TDesC& Name() 
                {
                // We can just return an LString directly as a const TDesC
                return iName; 
                }

protected:
        CStringUserTwoPhase()
                {
                /*
                Everything interesting happens in ConstructL in this
                version. 

                Default initialization of the iName LString does not
                allocate a heap buffer, and so cannot leave. As long as
                initialization is deferred to ConstructL, LStrings can be
                used safely with two-phase construction.
                */
                }

protected:
        LString iName;
        };

class CStringUserSinglePhase : public CBase
        {
public:
        /*
        This macro is necessary to ensure cleanup is correctly handled
        in the event that a constructor may leave beneath a call to
        new(ELeave)
        */
        CONSTRUCTORS_MAY_LEAVE

        static CStringUserSinglePhase* NewL(const TDesC& aName)
                {
                return new(ELeave) CStringUserSinglePhase(aName);
                }

        ~CStringUserSinglePhase()
                {
                // The iName LString cleans up after itself automatically
                }

        const TDesC& Name() 
                {
                // We can just return an LString directly as a const TDesC
                return iName;
                }

protected:
        CStringUserSinglePhase(const TDesC& aName)
                /*
                This initialization of iName may leave because LString
                needs to allocate a heap buffer to copy the aName string
                data into
                */
                : iName(aName) 
                {
                /*
                If iName initialization is successful but the constructor
                then goes on to leave later, iName (like all fields fully
                constructed at the point of a leave in a constructor) will
                be destructed, and so clean up after itself
                */
                MaybeLeave();
                }

protected:
        LString iName;
        };


void WalkthroughStringsL()
        {
        _LIT(KTxtOption1,"Option1: String handling using EUser high level library\n");
    gConsole->Printf(KTxtOption1);
    _LIT(KTxtFormatString,"String %d");
    _LIT(KTxtPrintString,"String %d = %S\n");
       {
                // Trivially exercise the LString using classes defined above

                LCleanedupPtr<CStringUserTwoPhase> one(CStringUserTwoPhase::NewL(KOne));
                _LIT(KTxtSinglePhaseConstructor,"Single phase name: %S\n");
                gConsole->Printf(KTxtSinglePhaseConstructor, &one->Name());

                LCleanedupPtr<CStringUserSinglePhase> two(CStringUserSinglePhase::NewL(KTwo));
                _LIT(KTxtTwoPhaseConstructor,"Single phase name: %S\n");
                gConsole->Printf(KTxtTwoPhaseConstructor, &two->Name());

                gConsole->Printf(KTxtPressAnyKeyToContinue);
                gConsole->Getch();
                // Both instances are automatically deleted as we go out of scope
                }

                {
                /*
                A default constructed LString starts empty, doesn't
                allocate any memory on the heap, and therefore the
                following cannot leave
                */
                LString s;

                /*
                But it will grow on demand if you assign to it, so it has
                enough space to hold the copied string data, and so
                assignment may leave
                */
                s = KOne;

                /*
                Similarly if you append to it with the leaving variant of
                Append(), AppendL(), if may grow on demand
                */
                s.AppendL(KTwo);

                // The += operator for LString also maps to AppendL()
                _LIT(KThree, "Three ");
                s += KThree;

                /*
                You can also use new leaving format methods that also grow
                on demand
                */
                s.AppendFormatL(KTesting);

                /*
                This general style of use of LString may be preferable to
                typical descriptor use for a number of reasons e.g. it
                avoids the common temptation to set an artificial maximum
                buffer size; it avoids massive conservative over-allocation
                when the average case length of a string is far less than
                the worst-case maximum; it will not surprise you (compared
                to the alternative of a large stack-allocated TBuf) by
                triggering stack overflow.
                */

                // An LString can be printed the same way as any descriptor
                _LIT(KTxtValue,"Value: %S\n");
                gConsole->Printf(KTxtValue, &s);

                // An LString can be compared the same way as any descriptor
                _LIT(KTxtLStringCompare," Comparing LString with a literal is successful\n");
                _LIT(KPhrase, "One Two Three Testing ");
                if(s == KPhrase)
                        {
                        gConsole->Printf(KTxtLStringCompare);
                        }

                // An LString supports all TDesC and TDes methods
                _LIT(KTxtLStringSupportedAPI1,"LString supports TDesC and TDes methods\n");
                if(s.Find(KTwo) == 4)
                        {
                        gConsole->Printf(KTxtLStringSupportedAPI1);     
                        }
                // An LString supports all TDesC and TDes operators
                _LIT(KTxtLStringSupportedAPI2,"LString supports TDesC and TDes operators\n");
                if(s[4] == TChar('T'))
                        {
                        gConsole->Printf(KTxtLStringSupportedAPI2);
                        }
                TInt untrimmed = s.Length();
                s.Trim();
                if(s.Length() == untrimmed - 1)
                        {
                        //LString supports Trim API
                        }

                s.UpperCase();
                _LIT(KTxtPrintUpperCase,"UpperCase: %S\n");
                gConsole->Printf(KTxtPrintUpperCase, &s);
                s.LowerCase();
                _LIT(KTxtPrintLowerCase,"UpperCase: %S\n");
                gConsole->Printf(KTxtPrintLowerCase, &s);
                gConsole->Printf(KTxtPressAnyKeyToContinue);
                gConsole->Getch();
                /*
                The underlying heap allocated buffer is released
                automatically when the LString goes out of scope, either
                normally or through a leave
                */
                }

                {
                // You can initialize with a MaxLength value
                LString s(KMaxFileName); // This operation may leave
                if(s.MaxLength() == KMaxFileName)
                        {       
                        //LString supports MaxLength API
                        }

                /*
                And you can dynamically adjust MaxLength later using 
                SetMaxLengthL() if you want an exact allocated size.
                Setting MaxLength() on construction or via SetMaxLengthL() is
                exact; calling MaxLength() immediately afterwards is
                guaranteed to return exactly the value you specified.
                */
                s.SetMaxLengthL(2 * KMaxFileName);
                if(s.MaxLength() == 2 * KMaxFileName)
                        {
                        //MaxLength is successfully adjusted.
                        }

                /*
                Pre-setting MaxLength is important when passing an LString
                as a TDes to a library function, because the LString can't
                be auto-grown via the TDes API.
                */

                }

                {
                /*
                You can initialize from any descriptor (or literal) and the
                string data is copied into the LString
                */
                LString s(KOne); // From a literal
                s += KTwo;
                LString half(s.Left(s.Length() / 2)); // Left returns a TPtrC
                _LIT(KTxtPrintAllandHalf,"All: %S, Half: %S\n");
                gConsole->Printf(KTxtPrintAllandHalf, &s, &half);

                /*
                On the other hand, you can initialize from a returned
                HBufC* and the LString automatically takes ownership
                */
                LString own(AllocateNameL(KTesting));
                _LIT(KTxtOwnedString,"What I own: %S\n");
                gConsole->Printf(KTxtOwnedString, &own);

                /*
                Following that you can re-assign an HBufC to an existing
                string using the assignment operator 
                taking ownership of the new content. 
                */
                own = AllocateNameL(KTesting);
                
                /*
                Following that you can re-assign an HBufC to an existing
                string. The string destroys its original content before
                taking ownership of the new content. 
                */
                own.Assign(AllocateNameL(KTesting));
                
                /*
                The content of one string can similarly be assigned
                to another to avoid copying. In this example, the content 
                is detached from 's' and transfered to 'own'.
                */  
                own.Assign(s);
                
                /*
                The same content transfer can be achieved from an RBuf to a
                string. You may need to do this if a legacy method returns
                you an RBuf. The RBuf is emptied of its content.
                */
                RBuf16 buf;
                buf.CreateL(KOne);
                own.Assign(buf);
        
                /*
                You can also assign a simple text array to a string as its
                new buffer. This method initialises the length to zero.
                */   
                own.Assign((TText*)User::Alloc(24*(TInt)sizeof(TText)), 24);
                
                /*
                If the buffer has already been filled with some characters
                then you supply the length in this alternative Assign() method.
                */   
                own.Assign((TText*)User::Alloc(24*(TInt)sizeof(TText)), 12,24);
                gConsole->Printf(KTxtPressAnyKeyToContinue);
                gConsole->Getch();
                /*
                Each Assign() destroys the old content before assuming ownership
                of the new.
                As usual the last content of the string is destroyed when the 
                LString goes out of scope
                */
                }

                {
                /*
                You can reserve extra free space in preparation for an 
                operation that adds characters to the string. You may
                need to do this when you cannot use any of the auto-buffer
                extending LString methods to achieve your objective.
                */
                LString s(KOne);
                s.ReserveFreeCapacityL(4);
                if(s.Length() == 4)
                        {
                        //Length() API gives the current length of the string
                        }
                if(s.MaxLength() >= 8)
                        {
                        //MaxLength() gives the maximum length supported by the string
                        }

                /*
                Almost all the methods that may extend the string buffer,
                including the explicit ReserveFreeCapacityL(), but excluding
                SetMaxLengthL(), attempt to grow the size exponentially. 
                The exponential growth pattern is expected to give better 
                performance at an amortised complexity of O(n) when adding n characters.
                If the exponential growth is less than the supplied extra size
                then the supplied size is used instead to save time.
                The exponential growth is used in anticipation of further additions
                to a string. This trades-off speed efficiency for space efficiency.
                If required you may be able to swap the oversized buffer for 
                a more compact one using:
                */
                s.Compress();
                if(s.MaxLength() >= 4)
                        {
                        //Compress() API is used to compress the unused memory.
                        }
                    
                /*
                Resize() attempts to re-allocate a smaller buffer to copy
                the content into. If the new memory cannot be allocated then the
                original string is left unaffected. 
                
                When you have finished using the content of a string you can
                get its buffer released without destroying the string itself. 
                You may want to do this when using member declared strings.
                Automatic strings are destroyed when they go out of scope.
                */
                s.Reset();
                if(s.Length() == 0)
                        {
                        //Buffer of the string is released, hence length is zero.
                        }
                if(s.MaxLength() == 0)
                        {
                        //Buffer of the string is released, hence maximum length is zero.
                        }
                
                }

                {
                /*
                An LString can be passed directly to any function requiring
                a const TDesC&
                */
                TInt year = 2009;

                LString s;
                _LIT(KTxtFormatYear1,"Happy New Year %d");
                s.FormatL(KTxtFormatYear1, year);
                // InfoPrint() takes a const TDesC&
                User::InfoPrint(s);

                LString pattern;
                _LIT(KTxtFormatYear2,"*Year %d");
                pattern.FormatL(KTxtFormatYear2, year);
                // Match() takes a const TDesC& as a pattern
                TInt loc = s.Match(pattern);
                if(loc == 10)
                        {
                        //Match() API is demonstrated successfully.
                        }
                }

                {
                /*
                An LString can be passed directly to any function requiring
                a TDes& but care must always be taken to pre-set MaxLength()
                since LStrings can't be automatically grown via the TDes
                interface
                */

                LString s;
                /*
                Calling GetCurrentPath(s) now would panic because LStrings
                are initialized by default to MaxLength 0.  Although s is
                an LString GetCurrentPath() takes a TDes& and so inside the function
                's' behaves as a TDes and would panic with USER 11 if the resulting 
                new length of s is greater than its maximum length.
                */
                if(s.MaxLength() == 0)
                        {
                        //LStrings are initialized by default to MaxLength 0
                        }

                /*
                Calling SetMaxLengthL() will automatically realloc the
                underlying buffer if required, and is guaranteed to leave
                MaxLength() equal to the specified value
                */
                s.SetMaxLengthL(KMaxFileName);
                GetCurrentPath(s);
                _LIT(KTxtPrintPath,"Path: %S\n");
                gConsole->Printf(KTxtPrintPath, &s);
                if(s == KPath)
                        {
                        //String comparison is successful
                        }

                /*
                If SetMaxLengthL() adjusts MaxLength() to be lower than the current
                Length(), the data is truncated to the new MaxLength() and
                Length() set to the new MaxLength().
                */
                s.SetMaxLengthL(s.Length() / 2);
                _LIT(KTxtTruncatedPath,"Truncated path: %S\n");
                gConsole->Printf(KTxtTruncatedPath, &s);
                if(s.Length() == s.MaxLength())
                        {
                        //String comparison is successful
                        }

                /*
                An initial MaxLength() can be specified when constructing an
                LString. Note that unlike the default constructor, this
                variant allocates and may leave.
                */
                LString s2(KMaxFileName);
                GetCurrentPath(s2);
                gConsole->Printf(KTxtPrintPath, &s2);
                if(s2 == KPath)
                        {
                        //String comparison is successful
                        }

                /*
                Your code and APIs can benefit from LString's auto-growth
                behaviour by accepting an LString to fill in as an output
                parameter. Using LString rather than TDes parameters means 
                that the function is able to safely increase the size of the 
                string as the LString will re-allocate as necessary
                */
                LString s3;
                // GetCurrentPathString() takes an LString&
                GetCurrentPathString(s3);
                gConsole->Printf(KTxtPrintPath, &s3);
                if(s3 == KPath)
                        {
                        //String comparison is successful
                        }

                /*
                As a well-defined value class, if you want to, LStrings can
                be passed and returned by value. This is relatively
                inefficient however due to the amount of copying and heap
                reallocation involved. 
                */
                LString s4(AppendCurrentPathStringL(s3));
                _LIT(KTxtAppendedPath,"Appended path: %S\n");
                gConsole->Printf(KTxtAppendedPath, &s4);
                if(s4.Length() == s3.Length() * 2)
                        {
                        //String comparison is successful
                        }
                }

                {
                /*
                LStrings can be allocated on the heap if necessary. 
                Then it can managed as part of an array of string pointers.
                */
                TInt n = 5;
                LCleanedupHandle<RPointerArray<LString>, TResetAndDestroy> sarray;
                
                for (TInt i = 0; i < n; ++i) 
                        {
                        LString* s = new(ELeave) LString;
                        s->FormatL(KTxtFormatString, i);
                        sarray->Append(s);
                        }

                for (TInt i = 0, n = sarray->Count(); i < n; ++i) 
                        {
                        LString tmp;
                        tmp.FormatL(KTxtFormatString, i);
                        if(tmp == *(*sarray)[i])
                                {
                                
                                }
                        gConsole->Printf(KTxtPrintString, i, (*sarray)[i]);
                        }

                }

                {
                /*
                Any allocation failure in new(ELeave)LString throws
                KErrNoMemory and cleans up fully after itself.
                */

                __UHEAP_MARK;
                TRAPD(status, new(ELeave) LString(100 * 1024 * 1024));
                if(status == KErrNoMemory)
                        {
                        //cleans up after itself fully, there is no need to take any further action.
                        }
                __UHEAP_MARKEND;
                }

                {
                /*
                Native C arrays (both heap and stack allocated) of LStrings
                also work, although their use is not recommended.
                */

                TInt n = 5;
                LCleanedupArray<LString> sarray(new(ELeave) LString[n]);

                for (TInt i = 0; i < n; ++i) 
                        {
                        sarray[i].FormatL(KTxtFormatString, i);
                        }

                for (TInt i = 0; i < n; ++i) 
                        {
                        LString tmp;
                        tmp.FormatL(KTxtFormatString, i);
                        if(tmp == sarray[i])
                                {
                                //comparison of strings is successful
                                }
                        gConsole->Printf(KTxtPrintString, i, &sarray[i]);
                        }

                }
                
        }

class CManagedUserTwoPhase : public CBase
        {
public:
        static CManagedUserTwoPhase* NewL(CTicker* aTicker)
                {
                /*
                We can use the resource management utility classes in
                two-phase if we want to.
                */
                LCleanedupPtr<CManagedUserTwoPhase> self(new(ELeave) CManagedUserTwoPhase);
                self->ConstructL(aTicker);
                /*
                Calling Unmanage() disables cleanup and yields the
                previously managed pointer so that it can be safely
                returned.
                */
                return self.Unmanage(); 
                }

        ~CManagedUserTwoPhase()
                {
                /*
                The iTicker manager will automatically delete the CTicker
                The iTimer manager will automatically Close() the RTimer.
                */
                }

        CTicker& Ticker()
                {
                // If we dereference the management object we get a CTicker&.
                return *iTicker;
                }

        RTimer& Timer()
                {
                // If we dereference the management object we get an RTimer&.
                return *iTimer;
                }

private:
        
        virtual void ConstructL(CTicker* aTicker)
                {
                // Take ownership and manage aTicker.
                iTicker = aTicker; 

                // Note use of -> to indirect through the management wrapper.
                iTimer->CreateLocal() OR_LEAVE; 
                }
        
        CManagedUserTwoPhase()
                {
                /*
                Everything interesting happens in ConstructL() in this
                version. 

                Default initialization of the iName LString does not
                allocate a heap buffer, and so cannot leave. As long as
                initialization is deferred to ConstructL(), LStrings can be
                used safely with two-phase construction.
                */
                }

private:
        // We have to use LManagedXxx for fields, not LCleanedupXxx
        LManagedPtr<CTicker> iTicker;
        LManagedHandle<RTimer> iTimer;
        };

class CManagedUserSinglePhase : public CBase
        {
public:
        /*
        This macro is necessary to ensure cleanup is correctly handled
        in the event that a constructor may leave beneath a call to
        new(ELeave)
        */
        CONSTRUCTORS_MAY_LEAVE

        static CManagedUserSinglePhase* NewL(CTicker* aTicker)
                {
                return new(ELeave) CManagedUserSinglePhase(aTicker);
                }

        ~CManagedUserSinglePhase()
                {
                /*
                The iTicker manager destructor will automatically Zap() the CTicker.
                The iTimer manager destructor will automatically Close() the RTimer.
                */
                }

        CTicker& Ticker()
                {
                // If we dereference the management object we get a CTicker&.
                return *iTicker;
                }

        RTimer& Timer()
                {
                // If we dereference the management object we get an RTimer&.
                return *iTimer;
                }

private:
        CManagedUserSinglePhase(CTicker* aTicker)
                /*
                Take ownership and manage aTicker. Note that initialization
                of the LManagedXxx classes does not actually leave, but
                initialization of the LCleanedupXxx classes can.
                */
                : iTicker(aTicker)
                {
                /*
                If iTicker initialization is successful but the constructor
                then goes on to leave later, iTicker (like all fields fully
                constructed at the point of a leave in a constructor) will
                be destructed, and the manager will cleanup the CTicker.

                Note use of -> to indirect through the management wrapper.
                */
                iTimer->CreateLocal(); 

                // Likewise if we leave here, both iTicker and iTimer will
                // undergo managed cleanup.
                MaybeLeave();
                }

private:
        // We have to use LManagedXxx for fields, not LCleanedupXxx.
        LManagedPtr<CTicker, TTickerZapStrategy> iTicker;
        LManagedHandle<RTimer> iTimer;
        };

//Class definition of trivial R-Class
class RSimple
        {
public:
        
        RSimple(){iData = NULL;}
        
        //Open function sets value
        void OpenL(TInt aValue)
                {
                iData = new(ELeave) TInt(aValue);
                }
        
        //Cleanup function – frees resource
        void Close()
                {
                delete iData;
                iData = NULL;
                }

        //Cleanup function – frees resource
        void Free()
                {
                delete iData;
                iData = NULL;
                }

        //Cleanup function – frees resource
        void ReleaseData()
                {
                delete iData;
                iData = NULL;
                }
        
        //static cleanup function – frees aRSimple resources
        static void Cleanup(TAny* aRSimple)
                {
                static_cast<RSimple*>(aRSimple)->Close();
                }


private:
        TInt* iData;

        };


DEFINE_CLEANUP_FUNCTION(RSimple, ReleaseData);


void WalkthroughManagedL()
        {
        _LIT(KTxtOption2,"Option2: Object creation and resource management using EUser high level library\n");
        gConsole->Printf(KTxtOption2);
                {
                // Trivially exercise the manager-using classes defined above.
                CTicker* ticker1 = new(ELeave) CTicker;
                LCleanedupPtr<CManagedUserTwoPhase> one(CManagedUserTwoPhase::NewL(ticker1));
                if(&one->Ticker() == ticker1)
                        {
                        _LIT(KTxtLCleanedupPtrDemo1,"Creating an instance of CTicker using LCleanedupPtr\n");
                        gConsole->Printf(KTxtLCleanedupPtrDemo1);
                        }
                one->Timer().Cancel(); // Just to check we can get at it

                CTicker* ticker2 = new(ELeave) CTicker;
                LCleanedupPtr<CManagedUserSinglePhase> two(CManagedUserSinglePhase::NewL(ticker2));
                if(&two->Ticker() == ticker2)
                        {
                        _LIT(KTxtLCleanedupPtrDemo2,"Creating second instance of CTicker using LCleanedupPtr\n");
                        gConsole->Printf(KTxtLCleanedupPtrDemo2);
                        }
                two->Timer().Cancel(); // Just to check we can get at it
        _LIT(KTxtLCleanedupPtr,"Both instances are automatically deleted as we go out of scope\n");
        gConsole->Printf(KTxtLCleanedupPtr);
        gConsole->Printf(KTxtPressAnyKeyToContinue);
        gConsole->Getch();
                }

                // Always use LCleanedupXxx for locals, not LManagedXxx

                {
                /*
                Behind the scenes the LCleanedupXxx constructors push a
                cleanup item onto the cleanup stack and so may leave. If
                there is a leave during construction, the supplied pointer
                will still get cleaned up.
                */
                LCleanedupPtr<CTicker> t(new(ELeave) CTicker);

                /*
                We can access CTicker's members via the management object
                using ->
                */
                t->Tick();
                t->Tock();
                if(t->iTicks == t->iTocks)
                        {
                        _LIT(KTxtLCleanedupPtrDemo3,"CTicker members access using LCleanedupPtr is successful\n");
                        gConsole->Printf(KTxtLCleanedupPtrDemo3);
                        gConsole->Printf(KTxtPressAnyKeyToContinue);
                gConsole->Getch();
                        }

                /*
                We can get at a reference to the managed object using *
                when we need to, e.g. if we need to pass it to a function.
                */
                RegisterTicker(*t); // Takes a CTicker&

                /*
                If some unfriendly interface needs a pointer rather than a
                ref, we have a couple of options.
                */
                RegisterTickerPtr(&*t); // Takes a CTicker*
                RegisterTickerPtr(t.Get()); // Takes a CTicker*

                /*
                Note the use of . in t.Get() above; this distinguishes
                operations on the managing type from operations on the
                managed object.
                
                When the management object goes out of scope, either
                normally or as the result of a leave, the managed object is
                automatically deleted.
                */
                }

                {
                /*
                Sometimes you need to protect something temporarily before
                transferring ownership e.g. by returning the pointer or
                passing it to a function that takes ownership.
                */

                LCleanedupPtr<CTicker> t(new(ELeave) CTicker);

                // Protected while we do this
                MaybeLeave(); 

                /*
                But now we want to hand it off, so we use Unmanage() to
                both return a pointer and break the management link
                */
                TakeTickerOwnership(t.Unmanage());
                
                /*
                Now when it goes out of scope, no cleanup action is
                performed.
                */
                }

                {
                /*
                If needed, it is possible to reuse a manager by using = to
                assign it a new managed object.
                */

                // Not managing anything to start with
                LCleanedupPtr<CTicker> t;
                if(t.Get() == NULL)
                        {
                        //Successfully initialised to NULL
                        }
                if(&*t == NULL)
                        {
                        //CTicker* value is also NULL
                        }

                for (TInt i = 0; i < 10; ++i)
                        {
                        /*
                        If an object is already being managed, it is cleaned up
                        before taking ownership of the new object.
                        */
                        t = new(ELeave) CTicker;
                        }
                /*
                We're left owning the final ticker instance, all prior
                instances having been automatically deleted.
                */
                }

                {
                // If you have stateful code where a pointer can sometimes be NULL.
                LCleanedupPtr<CTicker> t(new(ELeave) CTicker);

                // Does t refer to NULL?
                if (!t)
                        {
                        _LIT(KTxtNull,"LCleanedupPtr object refers to Null\n" );
                        gConsole->Printf(KTxtNull);
                        }

                t = NULL; // Also releases the currently managed CTicker 

                // Does t refer to a non-NULL pointer?
                if (t)
                        {
                        _LIT(KTxtNonNull,"LCleanedupPtr object refers to Non Null pointer\n" );
                        gConsole->Printf(KTxtNonNull);
                        }
                }

                {
                // LCleanedupPtr uses delete to cleanup by default, but alternative cleanups can be specified

                // We just want to free this one and not invoke the destructor
                LCleanedupPtr<CTicker, TPointerFree> t(static_cast<CTicker*>(User::AllocL(sizeof(CTicker))));

                // Now User::Free() is called when t goes out of scope
                }

                {
                /*
                As well as the stock options, custom cleanup policies can
                also be defined. See above for the definition of
                TTickerZap.
                */
                LCleanedupPtr<CTicker, TTickerZapStrategy> t(new(ELeave) CTicker);

                // Now Zap() is called on the CTicker instance when t goes out of scope
                }

                {
                /*
                LCleanedupHandle is very similar in behaviour to
                LCleanedupPtr, the main difference being that it can define
                and contain its own instance of a handle rather than
                being supplied one.
                */
                LCleanedupHandle<RTimer> t;

                // Again, access to managed handle members is via ->
                t->CreateLocal() OR_LEAVE;
                t->Cancel();

                //We can get a reference to the handle for passing to functions using *
                RegisterTimer(*t);

                /*
                When the management object goes out of scope, either
                normally or as the result of a leave, the managed object is
                automatically cleanup by calling Close() on it.
                */
                }

                {
                /*
                LCleanedupHandle calls Close() by default, but alternative
                cleanups can be specified.
                
                We want this RPointerArray cleanup with with
                ResetAndDestroy instead of Close().
                */
                LCleanedupHandle<RPointerArray<HBufC>, TResetAndDestroy> array;
                for (TInt i = 0; i < 10; ++i) 
                        {
                        array->AppendL(HBufC::NewL(5));
                        }

                //Now when array goes out of scope, ResetAndDestroy is called to clean it up.
                }

                {
                /*
                As well as the stock options, custom cleanup policies can
                also be defined. See above for the definition of TCancelClose.
                */
                LCleanedupHandle<RTimer, TCancelClose> t;
                t->CreateLocal();

                // Now Cancel() followed by Close() are called when t goes out of scope
                }


                {
                /*
                LCleanedupHandleRef calls Close() by default, but alternative
                cleanups can be specified.
                
                We want this RPointerArray cleanup with
                ResetAndDestroy instead of Close().
                */
                RPointerArray<HBufC> rar;
                // calls to functions that cannot leave here
                rar.Append(HBufC::NewL(5));
                rar.Append(HBufC::NewL(5));


                LCleanedupRef<RPointerArray<HBufC>, TResetAndDestroy> array(rar);
                // calls to functions that could leave here
                for (TInt i = 0; i < 10; ++i) 
                        {
                        array->AppendL(HBufC::NewL(5));
                        }

                // Now when array goes out of scope, ResetAndDestroy is called to clean it up
                }

                {
                /*
                Never mix direct cleanup stack API calls with management
                class use within the same function, because their
                interaction can be confusing and counter-intuitive. Avoid
                the use of LC methods that leave objects on the cleanup
                stack, and use L methods instead.

                If a badly-behaved API were to offer only an LC variant,
                you would have to use it as follows
                */
                HBufC* raw = HBufC::NewLC(5);
                // Must pop immediately to balance the cleanup stack, before instantiating the manager
                CleanupStack::Pop(); 
                LCleanedupPtr<HBufC> wrapped(raw);

                /*
                Never do this:
                LCleanedupPtr<HBufC> buf(HBufC::NewLC(5));
                CleanupStack::Pop();
                because the manager will be popped (having been pushed
                last), not the raw buf pointer as you might have hoped

                A cleaner alternative may be to write your own L function
                wrapper around the LC function supplied.

                Luckily this situation (an LC method without a
                corresponding L method) is rare in practice.
                */
                }

                {
                // Although rarely used on the Symbian platform, C++ arrays are supported with a custom management class
                LCleanedupArray<CTicker> array(new CTicker[5]);

                // The array is cleaned up with delete[] on scope exit
                }

                {
                /*
                Although most cases are best covered by applying custom
                cleanup policies to the management classes already
                described, there is also a general TCleanupItem style
                cleanup option.
                */
                TAny* data = NULL; // But could be anything
                LCleanedupGuard guard1(BespokeCleanupFunction, data);
                // On scope exit BespokeCleanupFunction() is called on data.

                LCleanedupGuard guard2(BespokeCleanupFunction, data);
                // But cleanup can also be disabled in this case, as follows:
                guard2.Dismiss();
                }
                
                {
                LCleanedupHandle<RFs> managedFs;
                managedFs->Connect();
                //default cleanup strategy is to call RFs::Close() on scope exit;
                }
                
                {
                LCleanedupHandle<RSimple, TFree> simple;
                simple->OpenL(23);
                //Specified cleanup strategy is to call RSimple::Free() on scope exit;
                }
        
                /*
                Because the DEFINE_CLEANUP_FUNCTION is defined above, the default
                cleanup function for RSimple is RSimple::ReleaseData() rather than
                RSimple::Close()
                */
                {
                LCleanedupHandle<RSimple> simple;
                simple->OpenL(23);
                //Custom cleanup strategy is to call RSimple::ReleaseData() on scope exit
                }
                
                {
                RSimple simple;
                
                //The RSimple class above defines a static cleanup function
                //RSimple::Cleanup().
                LCleanedupGuard guard(RSimple::Cleanup, &simple);

                simple.OpenL(10);
                
                //On scope exit RSimple::Cleanup() is called passing &simple.
                }
        }

void WalkthroughUsageL()
        {
        _LIT(KTxtOption3,"Option3: Memory used by EUser high level classes\n");
        gConsole->Printf(KTxtOption3);
        RFile file;
        
        _LIT(KTxtSizeofRFile,"Size of RFile = %d\n");
        gConsole->Printf(KTxtSizeofRFile, sizeof(file));
        
        LCleanedupHandle<RFile> cFile;
        
        _LIT(KTxtSizeofLCleanedupHandleRFile,"Size of LCleanedupHandle<RFile> = %d\n");
        gConsole->Printf(KTxtSizeofLCleanedupHandleRFile, sizeof(cFile));
        gConsole->Printf(KTxtPressAnyKeyToContinue);
        gConsole->Getch();
        
        LCleanedupRef<RFile> crFile(file);      
        _LIT(KTxtSizeofLCleanedupRefRFile,"Size of LCleanedupRef<RFile> = %d\n");
        gConsole->Printf(KTxtSizeofLCleanedupRefRFile, sizeof(crFile));
        gConsole->Printf(KTxtPressAnyKeyToContinue);
        gConsole->Getch();

        CTicker* tracker = new(ELeave) CTicker;
        _LIT(KTxtSizeofCTracker,"Size of CTracker* = %d\n");
        gConsole->Printf(KTxtSizeofCTracker, sizeof(tracker));
        gConsole->Printf(KTxtPressAnyKeyToContinue);
        gConsole->Getch();
        
        LCleanedupPtr<CTicker> cTracker(tracker);
        _LIT(KTxtSizeofLCleanedupHandleCTicker,"Size of LCleanedupPtr<CTicker> = %d\n");
        gConsole->Printf(KTxtSizeofLCleanedupHandleCTicker, sizeof(LCleanedupPtr<CTicker>));
        gConsole->Printf(KTxtPressAnyKeyToContinue);
        gConsole->Getch();
        }

TInt TestL()
        {
        gConsole=Console::NewL(KTxtExample,TSize(KConsFullScreen,KConsFullScreen));
        CleanupStack::PushL(gConsole);
        gConsole->Printf(KTxtExample);
        gConsole->Printf(KTxtPressAnyKeyToContinue);
        gConsole->Getch();      
        WalkthroughStringsL();
        gConsole->Printf(KTxtPressAnyKeyToContinue);
        gConsole->Getch();
        WalkthroughManagedL();
        gConsole->Printf(KTxtPressAnyKeyToContinue);
        gConsole->Getch();
        WalkthroughUsageL();
        _LIT(KTxtPressAnyKeyToExit,"\nPress any key to exit");
        gConsole->Printf(KTxtPressAnyKeyToExit);
        gConsole->Getch();
        CleanupStack::PopAndDestroy(gConsole); // delete the gConsole
        return KErrNone;
        }

TInt E32Main()
        {       
        __UHEAP_MARK;
        CTrapCleanup* cleanup=CTrapCleanup::New(); // Create clean-up stack.
        TInt status;
        if(cleanup!=NULL)
                {
            TRAP(status, TestL());
                __ASSERT_ALWAYS(!status,User::Panic(KTxtExample,status));
                }
        delete cleanup; // Delete clean-up stack.       
        __UHEAP_MARKEND;
        
        return status;
        }


// eof

---