/*

* 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