TB10.1 Example Applications: examples/SysLibs/EUserHLExample/src/euserhlexample.cpp Source File

00001 // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
+00002 // All rights reserved.
+00003 // This component and the accompanying materials are made available
+00004 // under the terms of "Eclipse Public License v1.0"
+00005 // which accompanies this distribution, and is available
+00006 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
+00007 //
+00008 // Initial Contributors:
+00009 // Nokia Corporation - initial contribution.
+00010 //
+00011 // Contributors:
+00012 //
+00013 // Description:
+00014 //
+00015 
+00016 #include <f32file.h>
+00017 #include <e32cons.h>
+00018 #include <euserhl.h>
+00019 
+00020 
+00021 _LIT(KTxtExample,"EUsableExample\n");
+00022 _LIT(KTxtPressAnyKeyToContinue,"Press any key to continue\n");
+00023 
+00024 CConsoleBase* gConsole;
+00025 
+00032 _LIT(KPath, "c:\\a\\b\\c");
+00033 _LIT(KOne, "One ");
+00034 _LIT(KTwo, "Two ");
+00035 _LIT(KTesting, "Testing ");
+00036 
+00037 void MaybeLeave()
+00038         {
+00039         // Some code that may leave
+00040         }
+00041 
+00042 HBufC* AllocateNameL(const TDesC& aDes)
+00043         {
+00044         return aDes.AllocL();
+00045         }
+00046 
+00047 void GetCurrentPath(TDes& aDes)
+00048         {
+00049         aDes = KPath;
+00050         }
+00051 
+00052 void GetCurrentPathString(LString& aString)
+00053         {
+00054         aString = KPath; // Will auto-grow if necessary, may leave
+00055         }
+00056 
+00057 LString AppendCurrentPathStringL(LString aString)
+00058         {
+00059         /*
+00060         This method accepts and returns LStrings by value. It works but
+00061         is not recommended due to the inherent inefficiencies.
+00062         */
+00063         LString result(aString);
+00064         result += KPath;
+00065         return result;
+00066         }
+00067 
+00068 class CTicker : public CBase
+00069         {
+00070 public:
+00071         void Tick() { ++iTicks; }
+00072         void Tock() { ++iTocks; }
+00073 
+00074         void Zap() { delete this; }
+00075 
+00076 public:
+00077         TInt iTicks;
+00078         TInt iTocks;
+00079         };
+00080 
+00081 // Defines a custom pointer cleanup policy that calls the Zap member
+00082 class TTickerZapStrategy
+00083         {
+00084 public:
+00085         static void Cleanup(CTicker* aPtr)
+00086                 {
+00087                 /*
+00088                 The general template/class scaffolding remains the same
+00089                 for all custom cleanups, just this cleanup body varies
+00090                 */
+00091                 aPtr->Zap();
+00092                 _LIT(KTxtPrintZapp, "Zapped CTicker\n");
+00093                 gConsole->Printf(KTxtPrintZapp);
+00094                 }
+00095         };
+00096 
+00097 void RegisterTicker(CTicker& aTicker)
+00098         {
+00099         (void)aTicker;
+00100         }
+00101 
+00102 void RegisterTickerPtr(CTicker* aTicker)
+00103         {
+00104         (void)aTicker;
+00105         }
+00106 
+00107 void TakeTickerOwnership(CTicker* aTicker)
+00108         {
+00109         delete aTicker;
+00110         }
+00111 
+00112 void RegisterTimer(RTimer& aTimer)
+00113         {
+00114         (void)aTimer;
+00115         }
+00116 
+00117 // Defines a custom handle cleanup policy that calls Cancel() then Close()
+00118 class TCancelClose
+00119         {
+00120 public:
+00121         template <class T>
+00122         static void Cleanup(T* aHandle)
+00123                 {
+00124                 /*
+00125                 The general template/class scaffolding remains the same
+00126                 for all custom cleanups, just this cleanup body varies
+00127                 */
+00128                 aHandle->Cancel();
+00129                 aHandle->Close();
+00130                 _LIT(KTxtCancel,"Cancel Closed RTimer\n");
+00131                 gConsole->Printf(KTxtCancel);
+00132                 }
+00133         };
+00134 
+00135 void BespokeCleanupFunction(TAny* /*aData*/)
+00136         {
+00137         _LIT(KTxtCleanup,"BespokeCleanupFunction\n");
+00138         gConsole->Printf(KTxtCleanup);
+00139         }
+00140 
+00141 // The walkthroughs themselves
+00142 
+00149 class CStringUserTwoPhase : public CBase
+00150         {
+00151 public:
+00152         static CStringUserTwoPhase* NewL(const TDesC& aName)
+00153                 {
+00154                 /*
+00155                 We can use the resource management utility classes in
+00156                 two-phase if we want.
+00157                 */
+00158                 LCleanedupPtr<CStringUserTwoPhase> self(new(ELeave) CStringUserTwoPhase);
+00159                 self->Construct(aName);
+00160                 /*
+00161                 Calling Unmanage() disables cleanup and yields the
+00162                 previously managed pointer so that it can be safely
+00163                 returned
+00164                 */
+00165                 return self.Unmanage(); 
+00166                 }
+00167 
+00168         virtual void Construct(const TDesC& aName)
+00169                 {
+00170                 /*
+00171                 This assignment may leave if LString fails to allocate a
+00172                 heap buffer large enough to hold the data in aName
+00173                 */
+00174                 iName = aName; 
+00175                 }
+00176 
+00177         ~CStringUserTwoPhase()
+00178                 {
+00179                 // The iName LString cleans up after itself automatically 
+00180                 }
+00181 
+00182         const TDesC& Name() 
+00183                 {
+00184                 // We can just return an LString directly as a const TDesC
+00185                 return iName; 
+00186                 }
+00187 
+00188 protected:
+00189         CStringUserTwoPhase()
+00190                 {
+00191                 /*
+00192                 Everything interesting happens in ConstructL in this
+00193                 version. 
+00194 
+00195                 Default initialization of the iName LString does not
+00196                 allocate a heap buffer, and so cannot leave. As long as
+00197                 initialization is deferred to ConstructL, LStrings can be
+00198                 used safely with two-phase construction.
+00199                 */
+00200                 }
+00201 
+00202 protected:
+00203         LString iName;
+00204         };
+00205 
+00217 class CStringUserSinglePhase : public CBase
+00218         {
+00219 public:
+00220         /*
+00221         This macro is necessary to ensure cleanup is correctly handled
+00222         in the event that a constructor may leave beneath a call to
+00223         new(ELeave)
+00224         */
+00225         CONSTRUCTORS_MAY_LEAVE
+00226 
+00227         static CStringUserSinglePhase* NewL(const TDesC& aName)
+00228                 {
+00229                 return new(ELeave) CStringUserSinglePhase(aName);
+00230                 }
+00231 
+00232         ~CStringUserSinglePhase()
+00233                 {
+00234                 // The iName LString cleans up after itself automatically
+00235                 }
+00236 
+00237         const TDesC& Name() 
+00238                 {
+00239                 // We can just return an LString directly as a const TDesC
+00240                 return iName;
+00241                 }
+00242 
+00243 protected:
+00244         CStringUserSinglePhase(const TDesC& aName)
+00245                 /*
+00246                 This initialization of iName may leave because LString
+00247                 needs to allocate a heap buffer to copy the aName string
+00248                 data into
+00249                 */
+00250                 : iName(aName) 
+00251                 {
+00252                 /*
+00253                 If iName initialization is successful but the constructor
+00254                 then goes on to leave later, iName (like all fields fully
+00255                 constructed at the point of a leave in a constructor) will
+00256                 be destructed, and so clean up after itself
+00257                 */
+00258                 MaybeLeave();
+00259                 }
+00260 
+00261 protected:
+00262         LString iName;
+00263         };
+00264 
+00265 
+00266 void WalkthroughStringsL()
+00267         {
+00268         _LIT(KTxtOption1,"Option1: String handling using EUser high level library\n");
+00269     gConsole->Printf(KTxtOption1);
+00270     _LIT(KTxtFormatString,"String %d");
+00271     _LIT(KTxtPrintString,"String %d = %S\n");
+00272        {
+00273                 // Trivially exercise the LString using classes defined above
+00274 
+00275                 LCleanedupPtr<CStringUserTwoPhase> one(CStringUserTwoPhase::NewL(KOne));
+00276                 _LIT(KTxtSinglePhaseConstructor,"Single phase name: %S\n");
+00277                 gConsole->Printf(KTxtSinglePhaseConstructor, &one->Name());
+00278 
+00279                 LCleanedupPtr<CStringUserSinglePhase> two(CStringUserSinglePhase::NewL(KTwo));
+00280                 _LIT(KTxtTwoPhaseConstructor,"Single phase name: %S\n");
+00281                 gConsole->Printf(KTxtTwoPhaseConstructor, &two->Name());
+00282 
+00283                 gConsole->Printf(KTxtPressAnyKeyToContinue);
+00284                 gConsole->Getch();
+00285                 // Both instances are automatically deleted as we go out of scope
+00286                 }
+00287 
+00288                 {
+00289                 /*
+00290                 A default constructed LString starts empty, doesn't
+00291                 allocate any memory on the heap, and therefore the
+00292                 following cannot leave
+00293                 */
+00294                 LString s;
+00295 
+00296                 /*
+00297                 But it will grow on demand if you assign to it, so it has
+00298                 enough space to hold the copied string data, and so
+00299                 assignment may leave
+00300                 */
+00301                 s = KOne;
+00302 
+00303                 /*
+00304                 Similarly if you append to it with the leaving variant of
+00305                 Append(), AppendL(), if may grow on demand
+00306                 */
+00307                 s.AppendL(KTwo);
+00308 
+00309                 // The += operator for LString also maps to AppendL()
+00310                 _LIT(KThree, "Three ");
+00311                 s += KThree;
+00312 
+00313                 /*
+00314                 You can also use new leaving format methods that also grow
+00315                 on demand
+00316                 */
+00317                 s.AppendFormatL(KTesting);
+00318 
+00319                 /*
+00320                 This general style of use of LString may be preferable to
+00321                 typical descriptor use for a number of reasons e.g. it
+00322                 avoids the common temptation to set an artificial maximum
+00323                 buffer size; it avoids massive conservative over-allocation
+00324                 when the average case length of a string is far less than
+00325                 the worst-case maximum; it will not surprise you (compared
+00326                 to the alternative of a large stack-allocated TBuf) by
+00327                 triggering stack overflow.
+00328                 */
+00329 
+00330                 // An LString can be printed the same way as any descriptor
+00331                 _LIT(KTxtValue,"Value: %S\n");
+00332                 gConsole->Printf(KTxtValue, &s);
+00333 
+00334                 // An LString can be compared the same way as any descriptor
+00335                 _LIT(KTxtLStringCompare," Comparing LString with a literal is successful\n");
+00336                 _LIT(KPhrase, "One Two Three Testing ");
+00337                 if(s == KPhrase)
+00338                         {
+00339                         gConsole->Printf(KTxtLStringCompare);
+00340                         }
+00341 
+00342                 // An LString supports all TDesC and TDes methods
+00343                 _LIT(KTxtLStringSupportedAPI1,"LString supports TDesC and TDes methods\n");
+00344                 if(s.Find(KTwo) == 4)
+00345                         {
+00346                         gConsole->Printf(KTxtLStringSupportedAPI1);     
+00347                         }
+00348                 // An LString supports all TDesC and TDes operators
+00349                 _LIT(KTxtLStringSupportedAPI2,"LString supports TDesC and TDes operators\n");
+00350                 if(s[4] == TChar('T'))
+00351                         {
+00352                         gConsole->Printf(KTxtLStringSupportedAPI2);
+00353                         }
+00354                 TInt untrimmed = s.Length();
+00355                 s.Trim();
+00356                 if(s.Length() == untrimmed - 1)
+00357                         {
+00358                         //LString supports Trim API
+00359                         }
+00360 
+00361                 s.UpperCase();
+00362                 _LIT(KTxtPrintUpperCase,"UpperCase: %S\n");
+00363                 gConsole->Printf(KTxtPrintUpperCase, &s);
+00364                 s.LowerCase();
+00365                 _LIT(KTxtPrintLowerCase,"UpperCase: %S\n");
+00366                 gConsole->Printf(KTxtPrintLowerCase, &s);
+00367                 gConsole->Printf(KTxtPressAnyKeyToContinue);
+00368                 gConsole->Getch();
+00369                 /*
+00370                 The underlying heap allocated buffer is released
+00371                 automatically when the LString goes out of scope, either
+00372                 normally or through a leave
+00373                 */
+00374                 }
+00375 
+00376                 {
+00377                 // You can initialize with a MaxLength value
+00378                 LString s(KMaxFileName); // This operation may leave
+00379                 if(s.MaxLength() == KMaxFileName)
+00380                         {       
+00381                         //LString supports MaxLength API
+00382                         }
+00383 
+00384                 /*
+00385                 And you can dynamically adjust MaxLength later using 
+00386                 SetMaxLengthL() if you want an exact allocated size.
+00387                 Setting MaxLength() on construction or via SetMaxLengthL() is
+00388                 exact; calling MaxLength() immediately afterwards is
+00389                 guaranteed to return exactly the value you specified.
+00390                 */
+00391                 s.SetMaxLengthL(2 * KMaxFileName);
+00392                 if(s.MaxLength() == 2 * KMaxFileName)
+00393                         {
+00394                         //MaxLength is successfully adjusted.
+00395                         }
+00396 
+00397                 /*
+00398                 Pre-setting MaxLength is important when passing an LString
+00399                 as a TDes to a library function, because the LString can't
+00400                 be auto-grown via the TDes API.
+00401                 */
+00402 
+00403                 }
+00404 
+00405                 {
+00406                 /*
+00407                 You can initialize from any descriptor (or literal) and the
+00408                 string data is copied into the LString
+00409                 */
+00410                 LString s(KOne); // From a literal
+00411                 s += KTwo;
+00412                 LString half(s.Left(s.Length() / 2)); // Left returns a TPtrC
+00413                 _LIT(KTxtPrintAllandHalf,"All: %S, Half: %S\n");
+00414                 gConsole->Printf(KTxtPrintAllandHalf, &s, &half);
+00415 
+00416                 /*
+00417                 On the other hand, you can initialize from a returned
+00418                 HBufC* and the LString automatically takes ownership
+00419                 */
+00420                 LString own(AllocateNameL(KTesting));
+00421                 _LIT(KTxtOwnedString,"What I own: %S\n");
+00422                 gConsole->Printf(KTxtOwnedString, &own);
+00423 
+00424                 /*
+00425                 Following that you can re-assign an HBufC to an existing
+00426                 string using the assignment operator 
+00427                 taking ownership of the new content. 
+00428                 */
+00429                 own = AllocateNameL(KTesting);
+00430                 
+00431                 /*
+00432                 Following that you can re-assign an HBufC to an existing
+00433                 string. The string destroys its original content before
+00434                 taking ownership of the new content. 
+00435                 */
+00436                 own.Assign(AllocateNameL(KTesting));
+00437                 
+00438                 /*
+00439                 The content of one string can similarly be assigned
+00440                 to another to avoid copying. In this example, the content 
+00441                 is detached from 's' and transfered to 'own'.
+00442                 */  
+00443                 own.Assign(s);
+00444                 
+00445                 /*
+00446                 The same content transfer can be achieved from an RBuf to a
+00447                 string. You may need to do this if a legacy method returns
+00448                 you an RBuf. The RBuf is emptied of its content.
+00449                 */
+00450                 RBuf16 buf;
+00451                 buf.CreateL(KOne);
+00452                 own.Assign(buf);
+00453         
+00454                 /*
+00455                 You can also assign a simple text array to a string as its
+00456                 new buffer. This method initialises the length to zero.
+00457                 */   
+00458                 own.Assign((TText*)User::Alloc(24*(TInt)sizeof(TText)), 24);
+00459                 
+00460                 /*
+00461                 If the buffer has already been filled with some characters
+00462                 then you supply the length in this alternative Assign() method.
+00463                 */   
+00464                 own.Assign((TText*)User::Alloc(24*(TInt)sizeof(TText)), 12,24);
+00465                 gConsole->Printf(KTxtPressAnyKeyToContinue);
+00466                 gConsole->Getch();
+00467                 /*
+00468                 Each Assign() destroys the old content before assuming ownership
+00469                 of the new.
+00470                 As usual the last content of the string is destroyed when the 
+00471                 LString goes out of scope
+00472                 */
+00473                 }
+00474 
+00475                 {
+00476                 /*
+00477                 You can reserve extra free space in preparation for an 
+00478                 operation that adds characters to the string. You may
+00479                 need to do this when you cannot use any of the auto-buffer
+00480                 extending LString methods to achieve your objective.
+00481                 */
+00482                 LString s(KOne);
+00483                 s.ReserveFreeCapacityL(4);
+00484                 if(s.Length() == 4)
+00485                         {
+00486                         //Length() API gives the current length of the string
+00487                         }
+00488                 if(s.MaxLength() >= 8)
+00489                         {
+00490                         //MaxLength() gives the maximum length supported by the string
+00491                         }
+00492 
+00493                 /*
+00494                 Almost all the methods that may extend the string buffer,
+00495                 including the explicit ReserveFreeCapacityL(), but excluding
+00496                 SetMaxLengthL(), attempt to grow the size exponentially. 
+00497                 The exponential growth pattern is expected to give better 
+00498                 performance at an amortised complexity of O(n) when adding n characters.
+00499                 If the exponential growth is less than the supplied extra size
+00500                 then the supplied size is used instead to save time.
+00501                 The exponential growth is used in anticipation of further additions
+00502                 to a string. This trades-off speed efficiency for space efficiency.
+00503                 If required you may be able to swap the oversized buffer for 
+00504                 a more compact one using:
+00505                 */
+00506                 s.Compress();
+00507                 if(s.MaxLength() >= 4)
+00508                         {
+00509                         //Compress() API is used to compress the unused memory.
+00510                         }
+00511                     
+00512                 /*
+00513                 Resize() attempts to re-allocate a smaller buffer to copy
+00514                 the content into. If the new memory cannot be allocated then the
+00515                 original string is left unaffected. 
+00516                 
+00517                 When you have finished using the content of a string you can
+00518                 get its buffer released without destroying the string itself. 
+00519                 You may want to do this when using member declared strings.
+00520                 Automatic strings are destroyed when they go out of scope.
+00521                 */
+00522                 s.Reset();
+00523                 if(s.Length() == 0)
+00524                         {
+00525                         //Buffer of the string is released, hence length is zero.
+00526                         }
+00527                 if(s.MaxLength() == 0)
+00528                         {
+00529                         //Buffer of the string is released, hence maximum length is zero.
+00530                         }
+00531                 
+00532                 }
+00533 
+00534                 {
+00535                 /*
+00536                 An LString can be passed directly to any function requiring
+00537                 a const TDesC&
+00538                 */
+00539                 TInt year = 2009;
+00540 
+00541                 LString s;
+00542                 _LIT(KTxtFormatYear1,"Happy New Year %d");
+00543                 s.FormatL(KTxtFormatYear1, year);
+00544                 // InfoPrint() takes a const TDesC&
+00545                 User::InfoPrint(s);
+00546 
+00547                 LString pattern;
+00548                 _LIT(KTxtFormatYear2,"*Year %d");
+00549                 pattern.FormatL(KTxtFormatYear2, year);
+00550                 // Match() takes a const TDesC& as a pattern
+00551                 TInt loc = s.Match(pattern);
+00552                 if(loc == 10)
+00553                         {
+00554                         //Match() API is demonstrated successfully.
+00555                         }
+00556                 }
+00557 
+00558                 {
+00559                 /*
+00560                 An LString can be passed directly to any function requiring
+00561                 a TDes& but care must always be taken to pre-set MaxLength()
+00562                 since LStrings can't be automatically grown via the TDes
+00563                 interface
+00564                 */
+00565 
+00566                 LString s;
+00567                 /*
+00568                 Calling GetCurrentPath(s) now would panic because LStrings
+00569                 are initialized by default to MaxLength 0.  Although s is
+00570                 an LString GetCurrentPath() takes a TDes& and so inside the function
+00571                 's' behaves as a TDes and would panic with USER 11 if the resulting 
+00572                 new length of s is greater than its maximum length.
+00573                 */
+00574                 if(s.MaxLength() == 0)
+00575                         {
+00576                         //LStrings are initialized by default to MaxLength 0
+00577                         }
+00578 
+00579                 /*
+00580                 Calling SetMaxLengthL() will automatically realloc the
+00581                 underlying buffer if required, and is guaranteed to leave
+00582                 MaxLength() equal to the specified value
+00583                 */
+00584                 s.SetMaxLengthL(KMaxFileName);
+00585                 GetCurrentPath(s);
+00586                 _LIT(KTxtPrintPath,"Path: %S\n");
+00587                 gConsole->Printf(KTxtPrintPath, &s);
+00588                 if(s == KPath)
+00589                         {
+00590                         //String comparison is successful
+00591                         }
+00592 
+00593                 /*
+00594                 If SetMaxLengthL() adjusts MaxLength() to be lower than the current
+00595                 Length(), the data is truncated to the new MaxLength() and
+00596                 Length() set to the new MaxLength().
+00597                 */
+00598                 s.SetMaxLengthL(s.Length() / 2);
+00599                 _LIT(KTxtTruncatedPath,"Truncated path: %S\n");
+00600                 gConsole->Printf(KTxtTruncatedPath, &s);
+00601                 if(s.Length() == s.MaxLength())
+00602                         {
+00603                         //String comparison is successful
+00604                         }
+00605 
+00606                 /*
+00607                 An initial MaxLength() can be specified when constructing an
+00608                 LString. Note that unlike the default constructor, this
+00609                 variant allocates and may leave.
+00610                 */
+00611                 LString s2(KMaxFileName);
+00612                 GetCurrentPath(s2);
+00613                 gConsole->Printf(KTxtPrintPath, &s2);
+00614                 if(s2 == KPath)
+00615                         {
+00616                         //String comparison is successful
+00617                         }
+00618 
+00619                 /*
+00620                 Your code and APIs can benefit from LString's auto-growth
+00621                 behaviour by accepting an LString to fill in as an output
+00622                 parameter. Using LString rather than TDes parameters means 
+00623                 that the function is able to safely increase the size of the 
+00624                 string as the LString will re-allocate as necessary
+00625                 */
+00626                 LString s3;
+00627                 // GetCurrentPathString() takes an LString&
+00628                 GetCurrentPathString(s3);
+00629                 gConsole->Printf(KTxtPrintPath, &s3);
+00630                 if(s3 == KPath)
+00631                         {
+00632                         //String comparison is successful
+00633                         }
+00634 
+00635                 /*
+00636                 As a well-defined value class, if you want to, LStrings can
+00637                 be passed and returned by value. This is relatively
+00638                 inefficient however due to the amount of copying and heap
+00639                 reallocation involved. 
+00640                 */
+00641                 LString s4(AppendCurrentPathStringL(s3));
+00642                 _LIT(KTxtAppendedPath,"Appended path: %S\n");
+00643                 gConsole->Printf(KTxtAppendedPath, &s4);
+00644                 if(s4.Length() == s3.Length() * 2)
+00645                         {
+00646                         //String comparison is successful
+00647                         }
+00648                 }
+00649 
+00650                 {
+00651                 /*
+00652                 LStrings can be allocated on the heap if necessary. 
+00653                 Then it can managed as part of an array of string pointers.
+00654                 */
+00655                 TInt n = 5;
+00656                 LCleanedupHandle<RPointerArray<LString>, TResetAndDestroy> sarray;
+00657                 
+00658                 for (TInt i = 0; i < n; ++i) 
+00659                         {
+00660                         LString* s = new(ELeave) LString;
+00661                         s->FormatL(KTxtFormatString, i);
+00662                         sarray->Append(s);
+00663                         }
+00664 
+00665                 for (TInt i = 0, n = sarray->Count(); i < n; ++i) 
+00666                         {
+00667                         LString tmp;
+00668                         tmp.FormatL(KTxtFormatString, i);
+00669                         if(tmp == *(*sarray)[i])
+00670                                 {
+00671                                 
+00672                                 }
+00673                         gConsole->Printf(KTxtPrintString, i, (*sarray)[i]);
+00674                         }
+00675 
+00676                 }
+00677 
+00678                 {
+00679                 /*
+00680                 Any allocation failure in new(ELeave)LString throws
+00681                 KErrNoMemory and cleans up fully after itself.
+00682                 */
+00683 
+00684                 __UHEAP_MARK;
+00685                 TRAPD(status, new(ELeave) LString(100 * 1024 * 1024));
+00686                 if(status == KErrNoMemory)
+00687                         {
+00688                         //cleans up after itself fully, there is no need to take any further action.
+00689                         }
+00690                 __UHEAP_MARKEND;
+00691                 }
+00692 
+00693                 {
+00694                 /*
+00695                 Native C arrays (both heap and stack allocated) of LStrings
+00696                 also work, although their use is not recommended.
+00697                 */
+00698 
+00699                 TInt n = 5;
+00700                 LCleanedupArray<LString> sarray(new(ELeave) LString[n]);
+00701 
+00702                 for (TInt i = 0; i < n; ++i) 
+00703                         {
+00704                         sarray[i].FormatL(KTxtFormatString, i);
+00705                         }
+00706 
+00707                 for (TInt i = 0; i < n; ++i) 
+00708                         {
+00709                         LString tmp;
+00710                         tmp.FormatL(KTxtFormatString, i);
+00711                         if(tmp == sarray[i])
+00712                                 {
+00713                                 //comparison of strings is successful
+00714                                 }
+00715                         gConsole->Printf(KTxtPrintString, i, &sarray[i]);
+00716                         }
+00717 
+00718                 }
+00719                 
+00720         }
+00721 
+00727 class CManagedUserTwoPhase : public CBase
+00728         {
+00729 public:
+00730         static CManagedUserTwoPhase* NewL(CTicker* aTicker)
+00731                 {
+00732                 /*
+00733                 We can use the resource management utility classes in
+00734                 two-phase if we want to.
+00735                 */
+00736                 LCleanedupPtr<CManagedUserTwoPhase> self(new(ELeave) CManagedUserTwoPhase);
+00737                 self->ConstructL(aTicker);
+00738                 /*
+00739                 Calling Unmanage() disables cleanup and yields the
+00740                 previously managed pointer so that it can be safely
+00741                 returned.
+00742                 */
+00743                 return self.Unmanage(); 
+00744                 }
+00745 
+00746         ~CManagedUserTwoPhase()
+00747                 {
+00748                 /*
+00749                 The iTicker manager will automatically delete the CTicker
+00750                 The iTimer manager will automatically Close() the RTimer.
+00751                 */
+00752                 }
+00753 
+00754         CTicker& Ticker()
+00755                 {
+00756                 // If we dereference the management object we get a CTicker&.
+00757                 return *iTicker;
+00758                 }
+00759 
+00760         RTimer& Timer()
+00761                 {
+00762                 // If we dereference the management object we get an RTimer&.
+00763                 return *iTimer;
+00764                 }
+00765 
+00766 private:
+00767         
+00768         virtual void ConstructL(CTicker* aTicker)
+00769                 {
+00770                 // Take ownership and manage aTicker.
+00771                 iTicker = aTicker; 
+00772 
+00773                 // Note use of -> to indirect through the management wrapper.
+00774                 iTimer->CreateLocal() OR_LEAVE; 
+00775                 }
+00776         
+00777         CManagedUserTwoPhase()
+00778                 {
+00779                 /*
+00780                 Everything interesting happens in ConstructL() in this
+00781                 version. 
+00782 
+00783                 Default initialization of the iName LString does not
+00784                 allocate a heap buffer, and so cannot leave. As long as
+00785                 initialization is deferred to ConstructL(), LStrings can be
+00786                 used safely with two-phase construction.
+00787                 */
+00788                 }
+00789 
+00790 private:
+00791         // We have to use LManagedXxx for fields, not LCleanedupXxx
+00792         LManagedPtr<CTicker> iTicker;
+00793         LManagedHandle<RTimer> iTimer;
+00794         };
+00795 
+00808 class CManagedUserSinglePhase : public CBase
+00809         {
+00810 public:
+00811         /*
+00812         This macro is necessary to ensure cleanup is correctly handled
+00813         in the event that a constructor may leave beneath a call to
+00814         new(ELeave)
+00815         */
+00816         CONSTRUCTORS_MAY_LEAVE
+00817 
+00818         static CManagedUserSinglePhase* NewL(CTicker* aTicker)
+00819                 {
+00820                 return new(ELeave) CManagedUserSinglePhase(aTicker);
+00821                 }
+00822 
+00823         ~CManagedUserSinglePhase()
+00824                 {
+00825                 /*
+00826                 The iTicker manager destructor will automatically Zap() the CTicker.
+00827                 The iTimer manager destructor will automatically Close() the RTimer.
+00828                 */
+00829                 }
+00830 
+00831         CTicker& Ticker()
+00832                 {
+00833                 // If we dereference the management object we get a CTicker&.
+00834                 return *iTicker;
+00835                 }
+00836 
+00837         RTimer& Timer()
+00838                 {
+00839                 // If we dereference the management object we get an RTimer&.
+00840                 return *iTimer;
+00841                 }
+00842 
+00843 private:
+00844         CManagedUserSinglePhase(CTicker* aTicker)
+00845                 /*
+00846                 Take ownership and manage aTicker. Note that initialization
+00847                 of the LManagedXxx classes does not actually leave, but
+00848                 initialization of the LCleanedupXxx classes can.
+00849                 */
+00850                 : iTicker(aTicker)
+00851                 {
+00852                 /*
+00853                 If iTicker initialization is successful but the constructor
+00854                 then goes on to leave later, iTicker (like all fields fully
+00855                 constructed at the point of a leave in a constructor) will
+00856                 be destructed, and the manager will cleanup the CTicker.
+00857 
+00858                 Note use of -> to indirect through the management wrapper.
+00859                 */
+00860                 iTimer->CreateLocal(); 
+00861 
+00862                 // Likewise if we leave here, both iTicker and iTimer will
+00863                 // undergo managed cleanup.
+00864                 MaybeLeave();
+00865                 }
+00866 
+00867 private:
+00868         // We have to use LManagedXxx for fields, not LCleanedupXxx.
+00869         LManagedPtr<CTicker, TTickerZapStrategy> iTicker;
+00870         LManagedHandle<RTimer> iTimer;
+00871         };
+00872 
+00873 //Class definition of trivial R-Class
+00874 class RSimple
+00875         {
+00876 public:
+00877         
+00878         RSimple(){iData = NULL;}
+00879         
+00880         //Open function sets value
+00881         void OpenL(TInt aValue)
+00882                 {
+00883                 iData = new(ELeave) TInt(aValue);
+00884                 }
+00885         
+00886         //Cleanup function � frees resource
+00887         void Close()
+00888                 {
+00889                 delete iData;
+00890                 iData = NULL;
+00891                 }
+00892 
+00893         //Cleanup function � frees resource
+00894         void Free()
+00895                 {
+00896                 delete iData;
+00897                 iData = NULL;
+00898                 }
+00899 
+00900         //Cleanup function � frees resource
+00901         void ReleaseData()
+00902                 {
+00903                 delete iData;
+00904                 iData = NULL;
+00905                 }
+00906         
+00907         //static cleanup function � frees aRSimple resources
+00908         static void Cleanup(TAny* aRSimple)
+00909                 {
+00910                 static_cast<RSimple*>(aRSimple)->Close();
+00911                 }
+00912 
+00913 
+00914 private:
+00915         TInt* iData;
+00916 
+00917         };
+00918 
+00919 
+00926 DEFINE_CLEANUP_FUNCTION(RSimple, ReleaseData);
+00927 
+00928 
+00929 void WalkthroughManagedL()
+00930         {
+00931         _LIT(KTxtOption2,"Option2: Object creation and resource management using EUser high level library\n");
+00932         gConsole->Printf(KTxtOption2);
+00933                 {
+00934                 // Trivially exercise the manager-using classes defined above.
+00935                 CTicker* ticker1 = new(ELeave) CTicker;
+00936                 LCleanedupPtr<CManagedUserTwoPhase> one(CManagedUserTwoPhase::NewL(ticker1));
+00937                 if(&one->Ticker() == ticker1)
+00938                         {
+00939                         _LIT(KTxtLCleanedupPtrDemo1,"Creating an instance of CTicker using LCleanedupPtr\n");
+00940                         gConsole->Printf(KTxtLCleanedupPtrDemo1);
+00941                         }
+00942                 one->Timer().Cancel(); // Just to check we can get at it
+00943 
+00944                 CTicker* ticker2 = new(ELeave) CTicker;
+00945                 LCleanedupPtr<CManagedUserSinglePhase> two(CManagedUserSinglePhase::NewL(ticker2));
+00946                 if(&two->Ticker() == ticker2)
+00947                         {
+00948                         _LIT(KTxtLCleanedupPtrDemo2,"Creating second instance of CTicker using LCleanedupPtr\n");
+00949                         gConsole->Printf(KTxtLCleanedupPtrDemo2);
+00950                         }
+00951                 two->Timer().Cancel(); // Just to check we can get at it
+00952         _LIT(KTxtLCleanedupPtr,"Both instances are automatically deleted as we go out of scope\n");
+00953         gConsole->Printf(KTxtLCleanedupPtr);
+00954         gConsole->Printf(KTxtPressAnyKeyToContinue);
+00955         gConsole->Getch();
+00956                 }
+00957 
+00958                 // Always use LCleanedupXxx for locals, not LManagedXxx
+00959 
+00960                 {
+00961                 /*
+00962                 Behind the scenes the LCleanedupXxx constructors push a
+00963                 cleanup item onto the cleanup stack and so may leave. If
+00964                 there is a leave during construction, the supplied pointer
+00965                 will still get cleaned up.
+00966                 */
+00967                 LCleanedupPtr<CTicker> t(new(ELeave) CTicker);
+00968 
+00969                 /*
+00970                 We can access CTicker's members via the management object
+00971                 using ->
+00972                 */
+00973                 t->Tick();
+00974                 t->Tock();
+00975                 if(t->iTicks == t->iTocks)
+00976                         {
+00977                         _LIT(KTxtLCleanedupPtrDemo3,"CTicker members access using LCleanedupPtr is successful\n");
+00978                         gConsole->Printf(KTxtLCleanedupPtrDemo3);
+00979                         gConsole->Printf(KTxtPressAnyKeyToContinue);
+00980                 gConsole->Getch();
+00981                         }
+00982 
+00983                 /*
+00984                 We can get at a reference to the managed object using *
+00985                 when we need to, e.g. if we need to pass it to a function.
+00986                 */
+00987                 RegisterTicker(*t); // Takes a CTicker&
+00988 
+00989                 /*
+00990                 If some unfriendly interface needs a pointer rather than a
+00991                 ref, we have a couple of options.
+00992                 */
+00993                 RegisterTickerPtr(&*t); // Takes a CTicker*
+00994                 RegisterTickerPtr(t.Get()); // Takes a CTicker*
+00995 
+00996                 /*
+00997                 Note the use of . in t.Get() above; this distinguishes
+00998                 operations on the managing type from operations on the
+00999                 managed object.
+01000                 
+01001                 When the management object goes out of scope, either
+01002                 normally or as the result of a leave, the managed object is
+01003                 automatically deleted.
+01004                 */
+01005                 }
+01006 
+01007                 {
+01008                 /*
+01009                 Sometimes you need to protect something temporarily before
+01010                 transferring ownership e.g. by returning the pointer or
+01011                 passing it to a function that takes ownership.
+01012                 */
+01013 
+01014                 LCleanedupPtr<CTicker> t(new(ELeave) CTicker);
+01015 
+01016                 // Protected while we do this
+01017                 MaybeLeave(); 
+01018 
+01019                 /*
+01020                 But now we want to hand it off, so we use Unmanage() to
+01021                 both return a pointer and break the management link
+01022                 */
+01023                 TakeTickerOwnership(t.Unmanage());
+01024                 
+01025                 /*
+01026                 Now when it goes out of scope, no cleanup action is
+01027                 performed.
+01028                 */
+01029                 }
+01030 
+01031                 {
+01032                 /*
+01033                 If needed, it is possible to reuse a manager by using = to
+01034                 assign it a new managed object.
+01035                 */
+01036 
+01037                 // Not managing anything to start with
+01038                 LCleanedupPtr<CTicker> t;
+01039                 if(t.Get() == NULL)
+01040                         {
+01041                         //Successfully initialised to NULL
+01042                         }
+01043                 if(&*t == NULL)
+01044                         {
+01045                         //CTicker* value is also NULL
+01046                         }
+01047 
+01048                 for (TInt i = 0; i < 10; ++i)
+01049                         {
+01050                         /*
+01051                         If an object is already being managed, it is cleaned up
+01052                         before taking ownership of the new object.
+01053                         */
+01054                         t = new(ELeave) CTicker;
+01055                         }
+01056                 /*
+01057                 We're left owning the final ticker instance, all prior
+01058                 instances having been automatically deleted.
+01059                 */
+01060                 }
+01061 
+01062                 {
+01063                 // If you have stateful code where a pointer can sometimes be NULL.
+01064                 LCleanedupPtr<CTicker> t(new(ELeave) CTicker);
+01065 
+01066                 // Does t refer to NULL?
+01067                 if (!t)
+01068                         {
+01069                         _LIT(KTxtNull,"LCleanedupPtr object refers to Null\n" );
+01070                         gConsole->Printf(KTxtNull);
+01071                         }
+01072 
+01073                 t = NULL; // Also releases the currently managed CTicker 
+01074 
+01075                 // Does t refer to a non-NULL pointer?
+01076                 if (t)
+01077                         {
+01078                         _LIT(KTxtNonNull,"LCleanedupPtr object refers to Non Null pointer\n" );
+01079                         gConsole->Printf(KTxtNonNull);
+01080                         }
+01081                 }
+01082 
+01083                 {
+01084                 // LCleanedupPtr uses delete to cleanup by default, but alternative cleanups can be specified
+01085 
+01086                 // We just want to free this one and not invoke the destructor
+01087                 LCleanedupPtr<CTicker, TPointerFree> t(static_cast<CTicker*>(User::AllocL(sizeof(CTicker))));
+01088 
+01089                 // Now User::Free() is called when t goes out of scope
+01090                 }
+01091 
+01092                 {
+01093                 /*
+01094                 As well as the stock options, custom cleanup policies can
+01095                 also be defined. See above for the definition of
+01096                 TTickerZap.
+01097                 */
+01098                 LCleanedupPtr<CTicker, TTickerZapStrategy> t(new(ELeave) CTicker);
+01099 
+01100                 // Now Zap() is called on the CTicker instance when t goes out of scope
+01101                 }
+01102 
+01103                 {
+01104                 /*
+01105                 LCleanedupHandle is very similar in behaviour to
+01106                 LCleanedupPtr, the main difference being that it can define
+01107                 and contain its own instance of a handle rather than
+01108                 being supplied one.
+01109                 */
+01110                 LCleanedupHandle<RTimer> t;
+01111 
+01112                 // Again, access to managed handle members is via ->
+01113                 t->CreateLocal() OR_LEAVE;
+01114                 t->Cancel();
+01115 
+01116                 //We can get a reference to the handle for passing to functions using *
+01117                 RegisterTimer(*t);
+01118 
+01119                 /*
+01120                 When the management object goes out of scope, either
+01121                 normally or as the result of a leave, the managed object is
+01122                 automatically cleanup by calling Close() on it.
+01123                 */
+01124                 }
+01125 
+01126                 {
+01127                 /*
+01128                 LCleanedupHandle calls Close() by default, but alternative
+01129                 cleanups can be specified.
+01130                 
+01131                 We want this RPointerArray cleanup with with
+01132                 ResetAndDestroy instead of Close().
+01133                 */
+01134                 LCleanedupHandle<RPointerArray<HBufC>, TResetAndDestroy> array;
+01135                 for (TInt i = 0; i < 10; ++i) 
+01136                         {
+01137                         array->AppendL(HBufC::NewL(5));
+01138                         }
+01139 
+01140                 //Now when array goes out of scope, ResetAndDestroy is called to clean it up.
+01141                 }
+01142 
+01143                 {
+01144                 /*
+01145                 As well as the stock options, custom cleanup policies can
+01146                 also be defined. See above for the definition of TCancelClose.
+01147                 */
+01148                 LCleanedupHandle<RTimer, TCancelClose> t;
+01149                 t->CreateLocal();
+01150 
+01151                 // Now Cancel() followed by Close() are called when t goes out of scope
+01152                 }
+01153 
+01154 
+01155                 {
+01156                 /*
+01157                 LCleanedupHandleRef calls Close() by default, but alternative
+01158                 cleanups can be specified.
+01159                 
+01160                 We want this RPointerArray cleanup with
+01161                 ResetAndDestroy instead of Close().
+01162                 */
+01163                 RPointerArray<HBufC> rar;
+01164                 // calls to functions that cannot leave here
+01165                 rar.Append(HBufC::NewL(5));
+01166                 rar.Append(HBufC::NewL(5));
+01167 
+01168 
+01169                 LCleanedupRef<RPointerArray<HBufC>, TResetAndDestroy> array(rar);
+01170                 // calls to functions that could leave here
+01171                 for (TInt i = 0; i < 10; ++i) 
+01172                         {
+01173                         array->AppendL(HBufC::NewL(5));
+01174                         }
+01175 
+01176                 // Now when array goes out of scope, ResetAndDestroy is called to clean it up
+01177                 }
+01178 
+01179                 {
+01180                 /*
+01181                 Never mix direct cleanup stack API calls with management
+01182                 class use within the same function, because their
+01183                 interaction can be confusing and counter-intuitive. Avoid
+01184                 the use of LC methods that leave objects on the cleanup
+01185                 stack, and use L methods instead.
+01186 
+01187                 If a badly-behaved API were to offer only an LC variant,
+01188                 you would have to use it as follows
+01189                 */
+01190                 HBufC* raw = HBufC::NewLC(5);
+01191                 // Must pop immediately to balance the cleanup stack, before instantiating the manager
+01192                 CleanupStack::Pop(); 
+01193                 LCleanedupPtr<HBufC> wrapped(raw);
+01194 
+01195                 /*
+01196                 Never do this:
+01197                 LCleanedupPtr<HBufC> buf(HBufC::NewLC(5));
+01198                 CleanupStack::Pop();
+01199                 because the manager will be popped (having been pushed
+01200                 last), not the raw buf pointer as you might have hoped
+01201 
+01202                 A cleaner alternative may be to write your own L function
+01203                 wrapper around the LC function supplied.
+01204 
+01205                 Luckily this situation (an LC method without a
+01206                 corresponding L method) is rare in practice.
+01207                 */
+01208                 }
+01209 
+01210                 {
+01211                 // Although rarely used on Symbian platform, C++ arrays are supported with a custom management class
+01212                 LCleanedupArray<CTicker> array(new CTicker[5]);
+01213 
+01214                 // The array is cleaned up with delete[] on scope exit
+01215                 }
+01216 
+01217                 {
+01218                 /*
+01219                 Although most cases are best covered by applying custom
+01220                 cleanup policies to the management classes already
+01221                 described, there is also a general TCleanupItem style
+01222                 cleanup option.
+01223                 */
+01224                 TAny* data = NULL; // But could be anything
+01225                 LCleanedupGuard guard1(BespokeCleanupFunction, data);
+01226                 // On scope exit BespokeCleanupFunction() is called on data.
+01227 
+01228                 LCleanedupGuard guard2(BespokeCleanupFunction, data);
+01229                 // But cleanup can also be disabled in this case, as follows:
+01230                 guard2.Dismiss();
+01231                 }
+01232                 
+01233                 {
+01234                 LCleanedupHandle<RFs> managedFs;
+01235                 managedFs->Connect();
+01236                 //default cleanup strategy is to call RFs::Close() on scope exit;
+01237                 }
+01238                 
+01239                 {
+01240                 LCleanedupHandle<RSimple, TFree> simple;
+01241                 simple->OpenL(23);
+01242                 //Specified cleanup strategy is to call RSimple::Free() on scope exit;
+01243                 }
+01244         
+01245                 /*
+01246                 Because the DEFINE_CLEANUP_FUNCTION is defined above, the default
+01247                 cleanup function for RSimple is RSimple::ReleaseData() rather than
+01248                 RSimple::Close()
+01249                 */
+01250                 {
+01251                 LCleanedupHandle<RSimple> simple;
+01252                 simple->OpenL(23);
+01253                 //Custom cleanup strategy is to call RSimple::ReleaseData() on scope exit
+01254                 }
+01255                 
+01256                 {
+01257                 RSimple simple;
+01258                 
+01259                 //The RSimple class above defines a static cleanup function
+01260                 //RSimple::Cleanup().
+01261                 LCleanedupGuard guard(RSimple::Cleanup, &simple);
+01262 
+01263                 simple.OpenL(10);
+01264                 
+01265                 //On scope exit RSimple::Cleanup() is called passing &simple.
+01266                 }
+01267         }
+01268 
+01269 void WalkthroughUsageL()
+01270         {
+01271         _LIT(KTxtOption3,"Option3: Memory used by EUser high level classes\n");
+01272         gConsole->Printf(KTxtOption3);
+01273         RFile file;
+01274         
+01275         _LIT(KTxtSizeofRFile,"Size of RFile = %d\n");
+01276         gConsole->Printf(KTxtSizeofRFile, sizeof(file));
+01277         
+01278         LCleanedupHandle<RFile> cFile;
+01279         
+01280         _LIT(KTxtSizeofLCleanedupHandleRFile,"Size of LCleanedupHandle<RFile> = %d\n");
+01281         gConsole->Printf(KTxtSizeofLCleanedupHandleRFile, sizeof(cFile));
+01282         gConsole->Printf(KTxtPressAnyKeyToContinue);
+01283         gConsole->Getch();
+01284         
+01285         LCleanedupRef<RFile> crFile(file);      
+01286         _LIT(KTxtSizeofLCleanedupRefRFile,"Size of LCleanedupRef<RFile> = %d\n");
+01287         gConsole->Printf(KTxtSizeofLCleanedupRefRFile, sizeof(crFile));
+01288         gConsole->Printf(KTxtPressAnyKeyToContinue);
+01289         gConsole->Getch();
+01290 
+01291         CTicker* tracker = new(ELeave) CTicker;
+01292         _LIT(KTxtSizeofCTracker,"Size of CTracker* = %d\n");
+01293         gConsole->Printf(KTxtSizeofCTracker, sizeof(tracker));
+01294         gConsole->Printf(KTxtPressAnyKeyToContinue);
+01295         gConsole->Getch();
+01296         
+01297         LCleanedupPtr<CTicker> cTracker(tracker);
+01298         _LIT(KTxtSizeofLCleanedupHandleCTicker,"Size of LCleanedupPtr<CTicker> = %d\n");
+01299         gConsole->Printf(KTxtSizeofLCleanedupHandleCTicker, sizeof(LCleanedupPtr<CTicker>));
+01300         gConsole->Printf(KTxtPressAnyKeyToContinue);
+01301         gConsole->Getch();
+01302         }
+01303 
+01304 TInt TestL()
+01305         {
+01306         gConsole=Console::NewL(KTxtExample,TSize(KConsFullScreen,KConsFullScreen));
+01307         CleanupStack::PushL(gConsole);
+01308         gConsole->Printf(KTxtExample);
+01309         gConsole->Printf(KTxtPressAnyKeyToContinue);
+01310         gConsole->Getch();      
+01311         WalkthroughStringsL();
+01312         gConsole->Printf(KTxtPressAnyKeyToContinue);
+01313         gConsole->Getch();
+01314         WalkthroughManagedL();
+01315         gConsole->Printf(KTxtPressAnyKeyToContinue);
+01316         gConsole->Getch();
+01317         WalkthroughUsageL();
+01318         _LIT(KTxtPressAnyKeyToExit,"\nPress any key to exit");
+01319         gConsole->Printf(KTxtPressAnyKeyToExit);
+01320         gConsole->Getch();
+01321         CleanupStack::PopAndDestroy(gConsole); // delete the gConsole
+01322         return KErrNone;
+01323         }
+01324 
+01325 TInt E32Main()
+01326         {       
+01327         __UHEAP_MARK;
+01328         CTrapCleanup* cleanup=CTrapCleanup::New(); // Create clean-up stack.
+01329         TInt status;
+01330         if(cleanup!=NULL)
+01331                 {
+01332             TRAP(status, TestL());
+01333                 __ASSERT_ALWAYS(!status,User::Panic(KTxtExample,status));
+01334                 }
+01335         delete cleanup; // Delete clean-up stack.       
+01336         __UHEAP_MARKEND;
+01337         
+01338         return status;
+01339         }
+01340 
+01341 
+01342 // eof
+