/*
* Copyright (c) 2006-2007 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:    Provides STUN relay binding services.
*
*/




#ifndef CSTUNRELAYBINDING_H
#define CSTUNRELAYBINDING_H

#include <e32base.h>
#include "natfwbindingbase.h"

/**
 * A class for sending Allocate Requests and 
 * obtaining the public IP address as seen by the STUN relay server.
 *
 * @lib      natfwstunclient.lib
 * @since    s60 v3.2
 */
class CSTUNRelayBinding : public CBinding
    {
public:

    /**
     * Two-phased constructor.
     *
     * @since   s60 v3.2
     * @pre     aSTUNClient.IsInitialized()
     * @param   aSTUNClient an initialized STUNClient
     * @param   aStreamId Stream identifier
     * @param   aConnectionId Connection identifier
     */
    IMPORT_C static CSTUNRelayBinding* NewL( CSTUNClient& aSTUNClient, 
        TUint aStreamId, TUint aConnectionId );

    /**
     * Two-phased constructor.
     *
     * @since   s60 v3.2
     * @pre     aSTUNClient.IsInitialized()
     * @param   aSTUNClient an initialised STUN client
     * @param   aStreamId Stream identifier
     * @param   aConnectionId Connection identifier
     */
    IMPORT_C static CSTUNRelayBinding* NewLC( CSTUNClient& aSTUNClient, 
        TUint aStreamId, TUint aConnectionId );        

    /**
     * Destructor.
     */
    IMPORT_C ~CSTUNRelayBinding();

    /**
     * Executes STUN relay binding request.
     * Refreshes the binding causing a new Allocate Request to be sent
     * to the STUN relay server. The public IP address is available when 
     * MSTUNClientObserver gets called.
     * If application provided credentials with CSTUNClient::SetCredentialsL
     * or if parameter aObtainSharedSecret was ETrue when CSTUNClient was
     * created, USERNAME and MESSAGE-INTEGRITY attributes are put into the
     * Binding Request.
     *
     * @since   s60 v3.2
     * @param   aRtoValue Retransmission timeout(0 = default value to be used)
     * @return  void
     */
    IMPORT_C void AllocateRequestL( TUint aRtoValue );

    /**
     * Once the client wants to primarily receive from one peer, it can send
     * SetActiveDestination request.
     *
     * @since   s60 v3.2
     * @param   aRemoteAddr Specified remote address
     * @param   aTimerValue Timer value got from server
     * @return  void
     */
    IMPORT_C void SetActiveDestinationRequestL( 
        const TInetAddr& aRemoteAddr, TUint32& aTimerValue );

    /**
     * After successfully AllocateRequestL and AddressResolved() calling
     * relayed transport address can be queried. 
     *  
     * @since   s60 v3.2
     * @return  relay transport address
     */
    IMPORT_C const TInetAddr& RelayAddr() const;

    /**
     * Transmission of data towards a peer
     * through the relay can be done using the SendIndicationL.
     * Indication does not generate response.
     *
     * @since   s60 v3.2
     * @param   aRemoteAddr     Address to send to (remote agent)
     * @param   aData           Data to send to remote agent. Use KNullDesC8
     *                          if there is no data available.
     * @param   aAddFingerprint true if fingerprint is added
     * @return  void
     */
    IMPORT_C void SendIndicationL( const TInetAddr& aRemoteAddr, 
        const TDesC8& aData, TBool aAddFingerprint );
        
    /**
     * ConnectRequestL is used (when obtained an
     * allocated transport address that is TCP) to request server to open
     * TCP connection to specific destination address.
     *
     * @since   s60 v3.2
     * @param   aRemoteAddr Specific remote address
     * @return  void
     */
    IMPORT_C void ConnectRequestL( const TInetAddr& aRemoteAddr );

    /**
     * From CBinding.
     * Cancels previously issued AllocateRequestL.
     *
     * @since   s60 v3.2
     * @return  void
     */
    IMPORT_C void CancelRequest();

    /**
     * From CBinding.
     * Checks whether the public address has a value set.
     *
     * @since   s60 v3.2
     * @return  ETrue if the public address has been obtained, 
     *          otherwise EFalse. 
     */
    IMPORT_C TBool AddressResolved() const;    

    /**
     * From CBinding.
     * Gets the public address for this binding as seen in public network.
     * If AddressResolved function returns EFalse, the return value of
     * this function is not defined.
     *
     * @since   s60 v3.2
     * @return public address
     */
    IMPORT_C const TInetAddr& PublicAddr() const;

    /**
     * From CBinding.
     * This method should be called when receiving data
     * from the socket shared with this binding and 
     * the data cannot be handled by client.
     *
     * @since   s60 v3.2
     * @param   aData data received
     * @param   aConsumed on return ETrue if the data was accepted,
     *          otherwise EFalse.
     * @param   aRemoteAddr remote address from remote address attribute
     * @return  Decoded data if data is indication and not unsaf message,
     *          otherwise NULL. Ownership is transferred.
     */
    IMPORT_C HBufC8* HandleDataL( 
        const TDesC8& aData, TBool& aConsumed, TInetAddr& aRemoteAddr );

    /**
     * From CBinding.
     * ICE specific attributes can be set for the request.
     *  
     * @since   s60 v3.2
     * @param   aAttributes     Contains ICE specific attributes.
     * @return  void
     */
    IMPORT_C void SetICESpecificAttributes( 
        const TICEAttributes& aAttributes );

    /**
     * From CBinding.
     * Returns used stream Id
     *
     * @since   s60 v3.2
     * @return  stream Id
     */
    IMPORT_C TUint StreamId() const;

    /**
     * From CBinding.
     * Returns used connection Id
     *
     * @since   s60 v3.2
     * @return  connection Id
     */
    IMPORT_C TUint ConnectionId() const;
        
    /**
     * From CBinding.
     * Returns alternate server transport address.
     *
     * @since   s60 v3.2
     * @return alternate server address
     */
    IMPORT_C const TInetAddr& AlternateServerAddr() const;

    /**
     * From CBinding.
     * Returns realm value from error response.
     *
     * @since   s60 v3.2
     * @return realm from error response         
     */
    IMPORT_C const HBufC8* RealmFromResponse() const;          
            
    /**
     * From CBinding.
     * Returns the associated CSTUNClient instance.
     *
     * @since   s60 v3.2
     * @return  CSTUNClient, or NULL if the CSTUNClient has been deleted        
     */
    IMPORT_C const CSTUNClient* STUNClient() const;


protected:

    /**
     * From CBinding.
     * Returns the implementation instance.        
     */
    CBindingImplementation& Implementation();
    
    /**
     * From CBinding.
     * Returns a non-modifiable implementation instance.        
     */
    const CBindingImplementation& Implementation() const;

private:

    CSTUNRelayBinding();
    CSTUNRelayBinding( const CBinding& aBinding );

    void ConstructL( CSTUNClient& aSTUNClient, TUint aStreamId,
        TUint aConnectionId );
    
    // This constructor is not used in this implementation    
    void ConstructL( CSTUNClient& aSTUNClient, RSocket& aSocket );
    
    __DECLARE_TEST;
    };

#endif // CSTUNRELAYBINDING_H