1 /*

     2 * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Cleanup Stack "reset and destroy" push operation.

    15  *

    16 */

    17 

    18 

    19 #ifndef CLEANUPRESETANDDESTROY_H

    20 #define CLEANUPRESETANDDESTROY_H

    21 

    22 //  INCLUDE FILES

    23 #include <e32base.h>

    24 

    25 /**

    26  * An operation for pushing objects to cleanup stack with \c TCleanupItems

    27  * that will perform a \c ResetAndDestroy() operation on the pushed object

    28  * if a leave occurs.

    29  *

    30  * Note that the object itself will not be deleted.

    31  *

    32  * @par Example:

    33  * Here is an example of using \c CleanupResetAndDestroy with a dynamically

    34  * allocated \c RPointerArray. \c RPointerArray clears its contents with a

    35  * \cResetAndDestroy() operation.

    36  * @code

    37  *

    38  *  // A function which creates a pointer array with couple of initialized

    39  *  // CThings. The function must return a pointer to the pointer array,

    40  *  // because the array has to be allocated dynamically. CThing is some

    41  *  // simple CBase-derived class.

    42  *

    43  *  RPointerArray< CThing >* CreateThingArrayL( )

    44  *      {

    45  *      // Create an array of pointers to CThings with granularity of 4

    46  *

    47  *      RPointerArray< CThing >* things =

    48  *          new( ELeave ) RPointerArray< CThing >( 4 );

    49  *

    50  *      // Push pointer to the array to the cleanup stack; then push reference

    51  *      // to the array and a ResetAndDestroy operation to the cleanup stack.

    52  *

    53  *      // (Note that order of these operations matters: the ResetAndDestroy

    54  *      // operation must be performed before the array itself is deleted.)

    55  *

    56  *      CleanupStack::PushL( things );

    57  *      CleanupResetAndDestroyPushL( *things );

    58  *

    59  *      // Add couple of CThings with magic numbers to the array.

    60  *      // If any of the NewL() operations leaves, the array will be cleared

    61  *      // with ResetAndDestroy() and the array itself will destroyed.

    62  *

    63  *      User::LeaveIfError( things->Append( CThing::NewL( 7 ) ) );

    64  *      User::LeaveIfError( things->Append( CThing::NewL( 96 ) ) );

    65  *      User::LeaveIfError( things->Append( CThing::NewL( 999 ) ) );

    66  *

    67  *      // Pop the array reference with ResetAndDestroy from cleanup stack

    68  *      // then pop the pointer to the array itself.

    69  *

    70  *      CleanupStack::Pop(); // *things

    71  *      CleanupStack::Pop(); // things

    72  *

    73  *      // Now we're ready to return the results (a pointer to the array)

    74  *      return things;

    75  *      }

    76  *

    77  * @endcode

    78  */

    79 template<class T>

    80 inline void CleanupResetAndDestroyPushL(T& aRef);

    81 

    82 /**

    83  *  <em>See \ref CleanupResetAndDestroyPushL() documentation.</em>

    84  */

    85 template<class T>

    86 class CleanupResetAndDestroy

    87 {

    88 public:

    89     inline static void PushL(T& aRef);

    90 

    91 private:

    92     static void ResetAndDestroy(TAny *aPtr);

    93 };

    94 

    95 template<class T>

    96 inline void CleanupResetAndDestroy<T>::PushL(T& aRef)

    97 {

    98     CleanupStack::PushL(TCleanupItem(&ResetAndDestroy, &aRef));

    99 }

   100 

   101 template<class T>

   102 void CleanupResetAndDestroy<T>::ResetAndDestroy(TAny *aPtr)

   103 {

   104     static_cast<T*>(aPtr)->ResetAndDestroy();

   105 }

   106 

   107 template<class T>

   108 inline void CleanupResetAndDestroyPushL(T& aRef)

   109 {

   110     CleanupResetAndDestroy<T>::PushL(aRef);

   111 }

   112 

   113 #endif // CLEANUPRESETANDDESTROY_H

   114 // End of File