/*
* Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:  Cleanup Stack "reset and destroy" push operation.
 *
*/


#ifndef CLEANUPRESETANDDESTROY_H
#define CLEANUPRESETANDDESTROY_H

//  INCLUDE FILES
#include <e32base.h>

/**
 * An operation for pushing objects to cleanup stack with \c TCleanupItems
 * that will perform a \c ResetAndDestroy() operation on the pushed object
 * if a leave occurs.
 *
 * Note that the object itself will not be deleted.
 *
 * @par Example:
 * Here is an example of using \c CleanupResetAndDestroy with a dynamically
 * allocated \c RPointerArray. \c RPointerArray clears its contents with a
 * \cResetAndDestroy() operation.
 * @code
 *
 *  // A function which creates a pointer array with couple of initialized
 *  // CThings. The function must return a pointer to the pointer array,
 *  // because the array has to be allocated dynamically. CThing is some
 *  // simple CBase-derived class.
 *
 *  RPointerArray< CThing >* CreateThingArrayL( )
 *      {
 *      // Create an array of pointers to CThings with granularity of 4
 *
 *      RPointerArray< CThing >* things =
 *          new( ELeave ) RPointerArray< CThing >( 4 );
 *
 *      // Push pointer to the array to the cleanup stack; then push reference
 *      // to the array and a ResetAndDestroy operation to the cleanup stack.
 *
 *      // (Note that order of these operations matters: the ResetAndDestroy
 *      // operation must be performed before the array itself is deleted.)
 *
 *      CleanupStack::PushL( things );
 *      CleanupResetAndDestroyPushL( *things );
 *
 *      // Add couple of CThings with magic numbers to the array.
 *      // If any of the NewL() operations leaves, the array will be cleared
 *      // with ResetAndDestroy() and the array itself will destroyed.
 *
 *      User::LeaveIfError( things->Append( CThing::NewL( 7 ) ) );
 *      User::LeaveIfError( things->Append( CThing::NewL( 96 ) ) );
 *      User::LeaveIfError( things->Append( CThing::NewL( 999 ) ) );
 *
 *      // Pop the array reference with ResetAndDestroy from cleanup stack
 *      // then pop the pointer to the array itself.
 *
 *      CleanupStack::Pop(); // *things
 *      CleanupStack::Pop(); // things
 *
 *      // Now we're ready to return the results (a pointer to the array)
 *      return things;
 *      }
 *
 * @endcode
 */
template<class T>
inline void CleanupResetAndDestroyPushL(T& aRef);

/**
 *  <em>See \ref CleanupResetAndDestroyPushL() documentation.</em>
 */
template<class T>
class CleanupResetAndDestroy
{
public:
    inline static void PushL(T& aRef);

private:
    static void ResetAndDestroy(TAny *aPtr);
};

template<class T>
inline void CleanupResetAndDestroy<T>::PushL(T& aRef)
{
    CleanupStack::PushL(TCleanupItem(&ResetAndDestroy, &aRef));
}

template<class T>
void CleanupResetAndDestroy<T>::ResetAndDestroy(TAny *aPtr)
{
    static_cast<T*>(aPtr)->ResetAndDestroy();
}

template<class T>
inline void CleanupResetAndDestroyPushL(T& aRef)
{
    CleanupResetAndDestroy<T>::PushL(aRef);
}

#endif // CLEANUPRESETANDDESTROY_H
// End of File