/*

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

* Name          : sipnattraversalcontroller.h

* Part of       : SIP NAT Traversal Controller

* Version       : SIP/5.0 

*

*/

#ifndef CSIPNATTRAVERSALCONTROLLER_H

#define CSIPNATTRAVERSALCONTROLLER_H

// INCLUDES

#include <e32base.h>

#include <ecom/ecom.h>

#include <es_sock.h>

#include <in_sock.h>

#include <securesocket.h>

// FORWARD DECLARATIONS

class MSIPNATBindingObserver;

class MSIPNATTraversalRequestObserver;

// CONSTANTS

/** Interface UID of this ECOM interface */

const TUid KSIPNATTraversalControllerIFUid = { 0x102747d0 };

// CLASS DECLARATION

/**

* @publishedPartner

* @released

*

* Interface for SIP NAT Traversal Controller ECOM plug-in(s).

*/

class CSIPNATTraversalController : public CBase

    {

    public: // Constructors and destructor

        /**

        * Destructor.

        */

        virtual inline ~CSIPNATTraversalController();

    public: // New functions

        /**

        * Resolves the public IP address and port related to 

        * the given IAP and UDP socket. 

        * This address will be used in the Contact-header 

        * of an outgoing SIP request.

        * @param aIapId IAP id

        * @param aConnection a opened and started connection

        * @param aLocalAddr a local address for the IAP

        * @param aDomain domain that can be used in service resolution

        *        in for example DNS queries for STUN service.

        * @param aUdpSocket handle to a UDP socket bind to the same local port 

        *        as the socket that will be used for sending SIP requests 

        *        and should be used for the public address discovery.

        * @param aNextHopAddr next hop IP address and port for 

        *        possibly needed NAT binding keepalives

        * @param aBindingObserver identifies the user for the 

        *        resources possibly reserved by this call. 

        *        If not NULL, can be later used for resource cleanup and

        *        will be informed if the created NAT binding fails.

        *        The ownership is not transferred.      

        * @param aRequestObserver observer to be informed when 

        *        the asynchronous request completes

        * @return a request ID

        */

        virtual TUint32 ResolvePublicAddrL(

            TUint32 aIapId,

            RConnection& aConnection,

            const TInetAddr& aLocalAddr,

            const TDesC8& aDomain,

            RSocket& aUdpSocket,

            const TInetAddr& aNextHopAddr,

            MSIPNATBindingObserver* aBindingObserver,

            MSIPNATTraversalRequestObserver& aRequestObserver ) = 0;

        /**

        * Cancels a particular outstanding request

        * @param aRequestId a request ID to be canceled

        */

        virtual void Cancel( TUint32 aRequestId ) = 0;        

        /**

        * Creates a NAT binding keepalive if the public address resolved

        * with ResolvePublicAddrL differs from the local IP address. 

        * If a keepalive already exists for aBindingObserver,

        * nothing should be done.

        * @param aSocket The socket that should be used 

        *        for NAT binding keepalives.

        * @param aBindingObserver identifies the user for the 

        *        resources possibly reserved by this call. 

        *        If not NULL, can be later used for resource cleanup and

        *        should be informed if the created NAT binding fails.

        *        The ownership is not transferred.

        * @return ETrue, if aSocket uses TCP and the TCP

        *         connection should be kept persistent 

        *         in order to allow the keepalive. 

        *         Otherwise EFalse. 

        */

        virtual TBool RefreshNATBindingL( 

            RSocket& aSocket,

            const MSIPNATBindingObserver* aBindingObserver ) = 0;

        /**

        * Creates a NAT binding keepalive if the public address resolved

        * with ResolvePublicAddrL differs from the local IP address. 

        * If a keepalive already exists for aBindingObserver,

        * nothing should be done.

        * @param aSecureSocket The socket that should be used 

        *        for NAT binding keepalives.

        * @param aBindingObserver identifies the user for the 

        *        resources possibly reserved by this call. 

        *        If not NULL, can be later used for resource cleanup and

        *        should be informed if the created NAT binding fails.

        *        The ownership is not transferred.

        * @return ETrue, if the TLS connection should be persistent.

        *         in order to allow the keepalive.

        *         Otherwise EFalse. 

        */

        virtual TBool RefreshNATBindingL(

            CSecureSocket& aSecureSocket,

            const MSIPNATBindingObserver* aBindingObserver ) = 0;

        /**

        * In case of a UDP based NAT binding keepalive,

        * the destination for the keepalive messages may change.

        * The new address must be taken into use if the

        * related aBindingObserver was found.

        * @param aNextHopAddr ETrue if idle otherwise EFalse

        * @param aBindingObserver identifies the NAT binding keepalive

        *        The ownership is not transferred.

        */

        virtual void UpdateNextHop( 

            const TInetAddr& aNextHopAddr,

            const MSIPNATBindingObserver* aBindingObserver ) = 0;

        /**

        * Informs that the socket is idle or not idle and 

        * can or cannot be used for sending. 

        * @param aIdle ETrue if idle otherwise EFalse

        * @param aSocket handle to the socket

        */    

        virtual void SocketIdle( 

            TBool aIdle,

            RSocket& aSocket ) = 0;

        /**

        * Informs that the socket is idle or not idle and 

        * can or cannot be used for sending. 

        * @param aIdle ETrue if idle otherwise EFalse

        * @param aSecureSocket handle to the TLS socket

        */    

        virtual void SocketIdle( 

            TBool aIdle,

            CSecureSocket& aSecureSocket ) = 0;

        /**

        * Data was received from a socket 

        * @param aData data received from the socket

        * @param aUdpSocket handle to the UDP socket

        * @param aHandle on return ETrue if the data was succesfully handled,

        *        otherwise EFalse.

        */    

        virtual void DataReceivedL( 

            const TDesC8& aData,

            const RSocket& aUdpSocket,

            TBool& aHandled ) = 0;    

        /**

        * Frees all the resources reserved related to an IAP.

        * @param aIapId IAP id

        */

        virtual void FreeResources( 

            TUint32 aIapId ) = 0;

        /**

        * Frees all the resources reserved for the observer.

        * @param aBindingObserver a observer

        */

        virtual void FreeResources( 

            MSIPNATBindingObserver& aBindingObserver ) = 0;

    public: // Data

        /// Unique key for implementations of this interface.

        TUid iInstanceKey;

    protected: // Constructors:

        inline CSIPNATTraversalController();

    };

#include "sipnattraversalcontroller.inl"

#endif // CSIPNATTRAVERSALCONTROLLER_H