/*

* Copyright (c) 2002 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 utility which resets a supplied pointer at PopAndDestroy().

*

*/

#ifndef     __DigCleanupResetPointer_H__

#define     __DigCleanupResetPointer_H__

//  INCLUDES

#include <e32base.h>

// CLASS DECLARATION

/**

 * @internal Only Phonebook internal use supported!

 *

 * Helper class for implementing CleanupResetPointerPushL function.

 * @see CleanupResetPointerPushL

 */

template<class PointerType>

class DigCleanupResetPointer 

    {

    private:

        /// Nampespace class -- constructor not implemented.

        DigCleanupResetPointer();

        /**

         * TCleanupItem callback for CleanupResetPointerPushL.

         * @see DigCleanupResetPointer::PushL

         */

        static void ResetPointerCallback(TAny* aPtrToPtrToReset);

    public:

        /**

         * Pushes a cleanup item on the cleanup stack which calls 

         * ResetPointerCallback on PopAndDestroy() to reset

         * aPointerToReset.

         *

         * @param aPointerToReset   pointer to the pointer to reset to NULL.

         * @exception   KErrNoMemory if cleanup stack runs out of memory. If this

         *              leave occurs the pointer is still reset to NULL (standard

         *              CleanupStack::PushL semantics).

         */

        inline static void PushL(PointerType*& aPointerToReset)

            {

            CleanupStack::PushL(TCleanupItem(ResetPointerCallback, &aPointerToReset));

            }

    };

template<class PointerType>

void DigCleanupResetPointer<PointerType>::ResetPointerCallback(TAny* aPtrToPtrToReset)

    {

    *static_cast<PointerType**>(aPtrToPtrToReset) = NULL;

    }

/**

 * Pushes a "reset pointer" cleanup item on the cleanup stack. 

 * When the "reset pointer" item is destroyed with CleanupStack::PopAndDestroy()

 * it resets the pointer variable passed in to NULL.<p>

 * 

 * Example:<br>

 * <pre>

 * CleanupResetPointerPushL(iFooDialog);

 * iFooDialog = new(ELeave) CFooDialog;

 * iFooDialog->ExecuteLD(R_FOO_DIALOG);

 * CleanupStack::PopAndDestroy();  // resets iFooDialog to NULL

 * </pre><p>

 *

 * Note that in the example above iFooDialog will be reset to NULL:

 * <ol>

 * <li>By the CleanupStack::PopAndDestroy() call after the ExecuteLD() call, or</li>

 * <li>by standard cleanup mechanism if ExecuteLD leaves.</li>

 * </ol>

 *

 * <p>The idea is to prevent a TRAP like here:</p>

 * <pre>

 * iFooDialog = new(ELeave) CFooDialog;

 * TRAPD(err, iFooDialog->ExecuteLD(R_FOO_DIALOG));

 * iFooDialog = NULL;

 * if (err) User::Leave(err);

 * </pre>

 *

 * @param aPointerToReset   pointer variable to reset to NULL on 

 *                          CleanupStack::PopAndDestroy() or leave.

 *

 * @exception   KErrNoMemory if cleanup stack runs out of memory. If this

 *              leave occurs the pointer is still reset to NULL (standard

 *              CleanupStack::PushL semantics).

 */

template<class PointerType>

inline void CleanupResetPointerPushL(PointerType*& aPointerToReset)

    {

    DigCleanupResetPointer<PointerType>::PushL(aPointerToReset);

    }

#endif

// End of File