/*
* 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 Client services.
*
*/




#ifndef CSTUNCLIENT_H
#define CSTUNCLIENT_H

#include <e32base.h>
#include <in_sock.h>
#include "natfwstunclientdefs.h"

class MSTUNClientObserver;
class CDeltaTimer;
class CSTUNClientImplementation;
class MNcmConnectionMultiplexer;

/**
 * A class for creating STUN bindings towards a particular STUN server.
 * During the initialization resolves the STUN server address using 
 * DNS queries and obtains a shared secret from the STUN server 
 * if required. Supports also STUN relay.
 * Client should set credentials if pre-provisioned ( also known as 
 * long term credentials ) just after NewL is called.
 * MSTUNClientObserver::STUNClientInitCompleted notifies when
 * STUN Client is initialized.
 *
 * @lib stunclient.lib
 */
class CSTUNClient : public CBase
    {
public:

    /**
     * Two-phased constructor.
     * Starts the initialization procedures for STUN Client.
     * MSTUNClientObserver::STUNClientInitCompleted gets called 
     * when the object is ready to be used.
     *
     * @param   aRetransmitInterval the initial retransmit interval 
     *          for STUN Binding Requests.
     * @param   aServerAddress FQDN or IP address of the STUN server.
     *          If FQDN, assumed to be a domain for which a SRV query 
     *          is performed. If SRV query fails a A/AAAA query is performed.
     * @param   aServerPort if not zero, 
     *          server port to be used instead of STUN default port. 
     * @param   aServiceName Client must tell used servicename
     *          "stun" if STUN used,
     *          "stun-relay" if STUN relay used.
     * @param   aSocketServ a connected socket server session
     * @param   aConnection an active connection started by the client
     *          with RConnection::Start()
     * @param   aTimer Timer services
     * @param   aObserver a callback for STUN Client event notifications
     * @param   aObtainSharedSecret if ETrue obtains a shared secret 
     *          which will be used for the STUN Binding Requests.
     *          If EFalse STUN Binding Requests will be sent without 
     *          the shared secret related attributes.
     * @param   aFailIfNoSRVRecordsFound if ETrue,
     *          MSTUNClientObserver::STUNClientInitCompleted 
     *          will be called with KErrNotFound, 
     *          if no SRV records for aSTUNServer with UDP were not found.
     * @param   aIcmpReceiverUsed Desides whether icmp receiver is
     *          instantiated in STUN client
     * @param   aMultiplexer Connection multiplexer.
     * @param   aTransportProtocol Transport protocol to use.
     */
    IMPORT_C static CSTUNClient* NewL( 
        TInt aRetransmitInterval,
        const TDesC8& aServerAddress,
        TUint aServerPort,
        const TDesC8& aServiceName,
        RSocketServ& aSocketServ,
        RConnection& aConnection,
        CDeltaTimer& aTimer,
        MSTUNClientObserver& aObserver,
        TBool aObtainSharedSecret=ETrue,
        TBool aFailIfNoSRVRecordsFound=EFalse,
        TBool aIcmpReceiverUsed=ETrue,
        MNcmConnectionMultiplexer* aMultiplexer=NULL,
        TTransportProtocol aTransportProtocol=EUdpProtocol );
    
    /**
     * Two-phased constructor.
     * Creates a new instance of CSTUNClient for ICE connectivity checks.
     * Starts the initialization procedures for STUN Client.
     * MSTUNClientObserver::STUNClientInitCompleted gets called 
     * when the object is ready to be used.
     *
     * @since   s60 v3.2
     * @param   aRetransmitInterval the initial retransmit interval 
     *          for STUN Binding Requests.
     * @param   aTimer Timer services
     * @param   aObserver a callback for STUN Client event notifications
     * @param   aMultiplexer Connection multiplexer.
     * @param   aTransportProtocol Used transport protocol.
     */
    IMPORT_C static CSTUNClient* NewL( 
        TInt aRetransmitInterval,
        CDeltaTimer& aTimer,
        MSTUNClientObserver& aObserver,
        MNcmConnectionMultiplexer* aMultiplexer=NULL,
        TTransportProtocol aTransportProtocol=EUdpProtocol );

    /**
     * Two-phased constructor.
     */
    IMPORT_C static CSTUNClient* NewLC( 
        TInt aRetransmitInterval,
        const TDesC8& aServerAddress,
        TUint aServerPort,
        const TDesC8& aServiceName,
        RSocketServ& aSocketServ,
        RConnection& aConnection,
        CDeltaTimer& aTimer,
        MSTUNClientObserver& aObserver,
        TBool aObtainSharedSecret=ETrue,
        TBool aFailIfNoSRVRecordsFound=EFalse,
        TBool aIcmpReceiverUsed=ETrue,
        MNcmConnectionMultiplexer* aMultiplexer=NULL,
        TTransportProtocol aTransportProtocol=EUdpProtocol );
    
    /**
     * Two-phased constructor.
     */
    IMPORT_C static CSTUNClient* NewLC( 
        TInt aRetransmitInterval,
        CDeltaTimer& aTimer,
        MSTUNClientObserver& aObserver,
        MNcmConnectionMultiplexer* aMultiplexer=NULL,
        TTransportProtocol aTransportProtocol=EUdpProtocol );

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

    /**
     * Check whether this STUN Client has been properly initialized
     * and can be used to create STUN bindings.
     *    
     * @return   ETrue if the client is initialized, otherwise EFalse
     */
    IMPORT_C TBool IsInitialized() const;

    /**
     * Gets the STUN server address and port used for 
     * when sending Binding Requests.
     *
     * @pre     IsInitialized() == ETrue
     * @leave   KErrNotReady if IsInitialized() == EFalse
     * @leave   KErrNotFound if STUN client has no responding addresses left
     * @return  STUN server used to keep the NAT bindings alive
     */
    IMPORT_C const TInetAddr& STUNServerAddrL() const;
    
    /**
     * Sets credentials for the STUN server used.
     * These credentials override any existing ones. They are used to
     * obtain short term shared secret or act as credentials as they are.
     *
     * @pre     aUsername's length must be larger than zero and multiple of 4.
     * @pre     aPassword's length must be larger than zero and multiple of 4.
     * @param   aUsername username
     * @param   aPassword password
     * @return  void
     */
    IMPORT_C void SetCredentialsL( const TDesC8& aUsername,
        const TDesC8& aPassword );

    /**
     * Tells if the Binding Requests will be sent protected with the
     * MESSAGE-INTEGRITY attribute.
     *
     * @return   ETrue if message integrity is used, EFalse otherwise
     */
    IMPORT_C TBool SharedSecretObtained() const;

    /**
     * Requests a new UNSAF transaction ID. ID's type is
     * TNATFWUNSAFTransactionID but it is casted as a descriptor as
     * only TURN Plug-in needs to obtain the ID from STUN Client API.
     *
     * @since   s60 v3.2
     * @param   aTransactionID OUT: New Transaction ID
     * @return  void
     */
    IMPORT_C void ObtainTransactionIDL( TDesC8& aTransactionID );
    
    CSTUNClientImplementation& Implementation();

private:

    CSTUNClient();

    CSTUNClient( const CSTUNClient& aClient );
    
    void ConstructL( TInt aRetransmitInterval,
                     const TDesC8& aServerAddress,
                     TUint aServerPort,
                     const TDesC8& aServiceName,
                     RSocketServ& aSocketServ,
                     RConnection& aConnection,
                     CDeltaTimer& aTimer,
                     MSTUNClientObserver& aObserver,
                     TBool aObtainSharedSecret,
                     TBool aFailIfNoSRVRecordsFound,
                     TBool aIcmpReceiverUsed,
                     MNcmConnectionMultiplexer* aMultiplexer,
                     TTransportProtocol aTransportProtocol );

    void ConstructL( TInt aRetransmitInterval,
                     CDeltaTimer& aTimer,
                     MSTUNClientObserver& aObserver,
                     MNcmConnectionMultiplexer* aMultiplexer,
                     TTransportProtocol aTransportProtocol );

private: // Data

    /** 
     * Implementation.
     * Own.
     */ 
    CSTUNClientImplementation* iImplementation;

private:

    __DECLARE_TEST;
    };

#endif // CSTUNCLIENT_H