/*
* Copyright (c) 2005 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:    
*
*/




#ifndef C_ASYNCCALLBACK_H
#define C_ASYNCCALLBACK_H

// INCLUDES
#include <e32base.h>
#include "tstuncallbackinfo.h"

// FORWARD DECLARATIONS
class MSTUNClientObserver;
class CBinding;

// CLASS DECLARATION
/*
 * CAsyncCallback is an active object used to guarantee that when the function
 * calls to the MSTUNClientObserver are made, the upper layer can delete any
 * STUN client related object it owns.
 */
class CAsyncCallback : public CActive
    {
public: // Constructor and destructor

    /**
     * Creates a new instance of CAsyncCallback.
     *
     * @param aObserver Observer implementing the callback functions
     * @return value New CAsyncCallback object. Ownership is transferred.
     */
    static CAsyncCallback* NewL( MSTUNClientObserver& aObserver );

    /**     
     * Frees the resources of CAsyncCallback. Any issued callback request that
     * have not yet been executed, are discarded.
     */
    ~CAsyncCallback();

public: // From CActive

    void DoCancel();

    void RunL();

    TInt RunError( TInt aError );

public: // New functions

    /**
     * Orders a specified callback function to be called, and provides all
     * necessary parameters.
     *     
     * @param aFunction Identifies the function of MSTUNClientObserver to use
     * @param aBinding STUN binding
     * @param aErrorCode Error reason
     * @param aClient STUN client     
     */
    void MakeCallbackL( TSTUNCallbackInfo::TFunction aFunction,
                        const CBinding* aBinding,
                        TInt aErrorCode = KErrNone,
                        const CSTUNClient* aClient = NULL );

    /**
     * Removes all pending callbacks, which have the specified binding as a
     * parameter.
     *
     * @param aBinding STUN binding     
     */
    void CancelCallback( const CBinding& aBinding );

    /**
     * Calls the oldest callback entry, if any.
     *
     * @param aBinding STUN binding     
     */
    void ExecuteFirstCallback();

private: // Constructors

    CAsyncCallback();

    CAsyncCallback( MSTUNClientObserver& aObserver );

    CAsyncCallback( const CAsyncCallback& aAsyncCallback );

private: // New functions, for internal use

    /**
     * Starts waiting for MakeCallbackL events.
     */
    void WaitForRequests();

    void Wakeup();

private: // Data

    // Implements the callback functions
    MSTUNClientObserver& iObserver;

    // Callback requests that have not yet been executed
    TSglQue<TSTUNCallbackInfo> iPendingCallbacks;

private: // For testing purposes

#ifdef TEST_EUNIT
    friend class CAsyncCallbackTest;
    friend class CSTUNClientTest;
#endif
    };

#endif // end of C_ASYNCCALLBACK_H

// End of File