/*

* 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 binding services.

*

*/

#ifndef CSTUNBINDING_H

#define CSTUNBINDING_H

#include <e32base.h>

#include "natfwbindingbase.h"

/**

 * A class for sending STUN Binding Requests and 

 * obtaining the public IP address as seen by the STUN server. 

 * @lib natfwstunclient.lib

 */

class CSTUNBinding : public CBinding

    {

    friend class CSTUNBindingTest;

    friend class ut_cstunclientimplementation;

public:

    /**

     * Two-phased constructor.

     * Associates the local socket with the binding.

     *

     * @pre     aSTUNClient.IsInitialized()

     * @pre     aSocket must have been opened

     * @param   aSTUNClient an initialised STUN client

     * @param   aSocket an opened socket that has the local port set.

     */

    IMPORT_C static CSTUNBinding* NewL( CSTUNClient& aSTUNClient,

        RSocket& aSocket );

    /**

     * Two-phased constructor.

     * Overloaded version.

     *

     * @since   s60 v3.2

     * @pre     aSTUNClient.IsInitialized()

     * @param   aSTUNClient an initialised STUN client

     * @param   aStreamId Stream identifier

     * @param   aConnectionId Connection identifier

     */

    IMPORT_C static CSTUNBinding* NewL( CSTUNClient& aSTUNClient, 

        TUint aStreamId, TUint aConnectionId );

    /**

     * Two-phased constructor.

     *

     * @pre     aSTUNClient.IsInitialized()

     * @pre     aSocket must have been opened

     * @param   aSTUNClient an initialised STUN client

     * @param   aSocket an opened socket that has the local port set.

     */

    IMPORT_C static CSTUNBinding* NewLC( CSTUNClient& aSTUNClient, 

        RSocket& aSocket );          

    /**

     * 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 CSTUNBinding* NewLC( CSTUNClient& aSTUNClient, 

        TUint aStreamId, TUint aConnectionId );          

    /**

     * Destructor.

     */

    IMPORT_C ~CSTUNBinding();

    /**

     * Executes STUN binding request.

     * Refreshes the binding causing a new Binding Request to be sent

     * to the STUN 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.

     *

     * @return  void

     */

    IMPORT_C void SendRequestL();

    /**

     * Overloaded version of SendRequestL().

     *

     * @since   s60 v3.2

     * @param   aDestAddr       Destination where to send request 

     *                          (KAFUnspec=default address)

     * @param   aAddFingerprint Whether to include fingerprint attribute

     *                          to request

     * @param   aRtoValue       Retransmission timeout

     *                          (0 = default value to be used)

     * @return  void

     */

    IMPORT_C void SendRequestL( const TInetAddr& aDestAddr,

        TBool aAddFingerprint, TUint aRtoValue );

    /**

     * Gets the socket used for obtaining the public address.

     *

     * @return  socket

     */

    IMPORT_C const RSocket& Socket() const;    

    /**

     * Specific cancel for stopping ongoing message retransmission.

     * Response is waited as long as transaction waiting time expires.

     * Client is notified by calling

     * MSTUNClientObserver::STUNBindingErrorOccurred.

     *

     * @since   s60 v3.2

     * @return  void

     */

    IMPORT_C void CancelRetransmission();

    /**

     * From CBinding.

     * Cancels a previously issued SendRequestL.

     */

    IMPORT_C void CancelRequest();

    /**

     * From CBinding

     * Send binding indication. Indications are not

     * retransmitted and responses are not expected.

     *

     * @since   s60 v3.2

     * @param   aRemoteAddr     address to send to (remote agent).

     * @param   aAddFingerprint add fingerprint attribute if true

     * @return  void

     */

    IMPORT_C void SendIndicationL( const TInetAddr& aRemoteAddr,

        const TDesC8& aData, TBool aAddFingerprint );

    /**

     * From CBinding.

     * Checks whether the public address has a value set.

     *

     * @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.

     *

     * @return  public transport 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.

     *

     * @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.

     * Query used stream ID

     *

     * @since   s60 v3.2

     * @return  stream Id

     */

    IMPORT_C TUint StreamId() const;

    /**

     * From CBinding.

     * Query 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.

     *

     * @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:

    CSTUNBinding();

    CSTUNBinding( const CBinding& aBinding );

    void ConstructL( CSTUNClient& aSTUNClient, RSocket& aSocket );

    void ConstructL( CSTUNClient& aSTUNClient, TUint aStreamId, 

        TUint aConnectionId );

    __DECLARE_TEST;

    };

#endif // CSTUNBINDING_H