/*

* Copyright (c) 2006 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:    Implementation classs of the NAT Connectivity FW

*

*/

#ifndef NATFWCLIENT_H

#define NATFWCLIENT_H

#include "natfwconnectivityapi.h"

#include "mncmconnectionmultiplexerobserver.h"

#include "mnatfwregistrationcontroller.h"

class CNcmConnectionMultiplexer;

class MNATFWSocketMediaConnWrapper;

class CNATFWSession;

class CNATFWStream;

class CNatFwAsyncCallback;

/**

 *  The implementation class of the NAT Connectivity FW

 *

 *  Implemets the NAT connectivity FW API

 *

 *  @lib natconfw.lib

 *  @since S60 v3.2

 */

NONSHARABLE_CLASS( CNATFWClient ) : public CBase,

    public MNcmConnectionMultiplexerObserver,

    public MNATFWRegistrationController

    {

    friend class UT_CNATFWClient;

public:

    static CNATFWClient* NewL();

    static CNATFWClient* NewLC();

    virtual ~CNATFWClient();

    /**

     * Registers given observer for the specified events. Same observer can be

     * registered for several events. Also several observers can be registered

     * for the same event. In that case each observer receives own copy of

     * eventdata.

     *

     * Refer to MNATFWConnectivityObserver API for event definitions.

     *

     * @since   S60 v3.2

     * @param   aObserver       Observer for NAT Connectivity API events

     * @param   aEvents         Events for which to register

     * @leave   KErrAlreadyExists Observer is already registered for some of

     *  the events

     */

    void RegisterObserverForEventsL( MNATFWConnectivityObserver& aObserver,

        TUint16 aEvents );

    /**

     * Unregisters given observer for the specified events.

     *

     * Refer to MNATFWConnectivityObserver API for event definitions.

     *

     * @since   S60 v3.2

     * @param   aObserver       Observer for NAT Connectivity API events

     * @param   aEvents         Events for which to unregister

     * @post    Observer will not receive notifications for specified events

     *          any more.

     */

    void UnregisterObserverForEvents( MNATFWConnectivityObserver& aObserver,

        TUint16 aEvents );

    /**

     * Creates a new session for the client. On return the client receives

     * identifier for the session. The session is ready to be used when the

     * client receives a callback to MNATFWConnectivityObserver::Notify

     * function with event code ESessionCreated.

     *

     * @since   S60 v3.2

     * @param   aIapId          The IAP used for a connection

     * @param   aDomain         Used domain for settings query

     * @return  The ID for the created session

     */

    TUint CreateSessionL( TUint32 aIapId, const TDesC8& aDomain );

    /**

     * Loads a NAT protocol plugin to the session. Old plugin is destroyed if

     * it exists. In this case NAT operations for the session must be started

     * anew ( FetchCandidate(s) and possible ICE processing ).

     *

     * Given NAT protocol plugins are tried to be loaded in order until a

     * working one is found.

     *

     * @since   S60 v3.2

     * @pre     NAT session is created

     * @param   aSessionId      The ID identifying session

     * @param   aPlugins        Array containing identifiers for available

     *          NAT-protocol plugins in preferred order. E.g.

     *          "exampleprovider.stun".

     * @param   aLoadedPluginInd Index to the aPlugins array telling actually

     *  loaded plugin.

     * @post    NAT protocol plugin is loaded and session is ready for use

     * @leave   KErrNotFound NAT-plugin was not found

     */

    void LoadPluginL( TUint aSessionId, const CDesC8Array& aPlugins,

        TInt& aLoadedPluginInd );

    /**

     * Creates a new stream for the client. On return the client receives a

     * stream ID.

     *

     * @since   S60 v3.2

     * @param   aSessionId      The ID identifying session

     * @param   aProtocol       KProtocolInetUdp / KProtocolInetTcp

     * @param   aQoS            The desired quality of service.

     * @return  The ID for the created stream

     */

    TUint CreateStreamL( TUint aSessionId,

        TUint aProtocol, TInt aQoS );

    /**

     * Creates a wrapper for the specified stream.

     *

     * @since   S60 v3.2

     * @param   aSessionId      The ID identifying session

     * @param   aStreamId       The ID identifying stream

     * @return  The interface through which the client can configure the wrapper.

     */

    MNATFWSocketMediaConnWrapper& CreateWrapperL(

        TUint aSessionId, TUint aStreamId );

    /**

     * Resolves public IP address to be used in the communication between

     * peers. MNATFWConnectivityObserver::NewLocalCandidateFound

     * is called when a public IP has been resolved.

     *

     * @since   S60 v3.2

     * @param   aSessionId      The ID identifying session

     * @param   aStreamId       The ID identifying stream

     * @param   aAddrFamily     KAFUnspec / KAfInet / KAfInet6

     */

    void FetchCandidateL( TUint aSessionId, TUint aStreamId,

        TUint aAddrFamily );

    /**

     * ICE spesific function. Fetches IP address candidates for the

     * communication between peers. Client is responsible for providing

     * mapping between components of media stream through collection ID

     * parameter. MNATFWConnectivityObserver::NewLocalCandidateFound

     * is called whenever a new candidate has been found.

     *

     * @since   S60 v3.2

     * @param   aSessionId      The ID identifying session

     * @param   aStreamId       The ID identifying stream

     * @param   aCollectionId   The stream collection identifier

     * @param   aComponentId    The media component identifier

     * @param   aAddrFamily     KAFUnspec / KAfInet / KAfInet6

     */

    void FetchCandidatesL(

        TUint aSessionId, TUint aStreamId,

        TUint aCollectionId, TUint aComponentId, TUint aAddrFamily );

    /**

     * ICE specific function.

     * Sets the role of local ICE agent. In role-conflict situation given role

     * will be silently changed.

     *

     * @since   S60 v3.2

     * @param   aSessionId      The ID identifying session

     * @param   aRole           The role

     */

    void SetRoleL( TUint aSessionId, TNATFWIceRole aRole );

    /**

     * ICE specific function. Set username fragment and corresponding

     * password for message signing and authentication with the specified

     * candidate.

     *

     * @since   S60 v3.2

     * @param   aCandidate      The candidate

     * @param   aCredentials    The credentials

     */

    void SetCredentialsL(

        CNATFWCandidate& aCandidate,

        const CNATFWCredentials& aCredentials );

    /**

     * ICE specific function.

     * Performs connectivity checks between the local candidates and the

     * remote candidates. MNATFWConnectivityObserver::NewCandidatePairFound

     * is called once per NATFW stream when ICE has selected working

     * candidate pair to be used for media in that stream.

     *

     * @since   S60 v3.2

     * @param   aSessionId      The ID identifying session

     * @param   aRemoteCands    The remote candidate array

     */

    void PerformConnectivityChecksL( TUint aSessionId,

        RPointerArray<CNATFWCandidate>& aRemoteCands );

    /**

     * ICE specific function.

     * Updates ICE processing for a session with the candidate pairs selected

     * by the controlling peer. If ICE processing for a stream is completed,

     * update for that is silently ignored.

     *

     * ICE restart is handled by setting new role and credentials and

     * re-starting connectivity checks with PerformCandidateChecksL.

     *

     * Adding new streams does not differ from initial operation.

     * Removing of streams is handled with CloseStreamL.

     *

     * Should a candidate use an FQDN as transport address, the corresponding

     * IP address shall be updated to it using A/AAAA queries.

     *

     * @since   S60 v3.2

     * @pre     ICE processing is started with PerformConnectivityChecksL

     * @param   aSessionId          The ID identifying session

     * @param   aPeerSelectedPairs  Peer selected candidate pairs

     * @leave   KErrNotSupported Loaded NAT Protocol plugin does not support

     * operation.

     * @post    ICE processing is continued with new parameters

     */

    void UpdateIceProcessingL( TUint aSessionId,

        RPointerArray<CNATFWCandidatePair>& aPeerSelectedPairs );

    /**

     * ICE specific function.

     * Updates ICE processing for a session with an updated set of remote

     * candidates. If ICE processing for a stream is completed, update for

     * that is silently ignored. New remote candidates will be included in

     * connectivity tests from this point onwards.

     *

     * ICE restart is handled by setting new role and credentials and

     * re-starting connectivity checks with PerformCandidateChecksL.

     *

     * Adding new streams does not differ from initial operation.

     * Removing of streams is handled with CloseStreamL.

     *

     * Should a candidate use an FQDN as transport address, the corresponding

     * IP address shall be updated to it using A/AAAA queries.

     *

     * @since   S60 v3.2

     * @pre     ICE processing is started with PerformConnectivityChecksL

     * @param   aSessionId          The ID identifying session

     * @param   aRemoteCands        All remote candidates known currently

     * @leave   KErrNotSupported Loaded NAT Protocol plugin does not support

     * operation.

     * @post    ICE processing is continued with new parameters

     */

    void UpdateIceProcessingL( TUint aSessionId,

        RPointerArray<CNATFWCandidate>& aRemoteCands );

    /**

     * Enables/disables media receiving for the specified local candidate.

     * 

     * Only those candidates given with MNATFWConnectivityObserver callbacks

     * can be controlled. NATFW stream can have only one active candidate

     * at a time. In other words, exactly one local candidate can be used

     * for media delivery in receiving, sending or both directions.

     * 

     * Receiving must be disabled prior to closing stream so that all

     * resources can be freed.

     * 

     * MNATFWConnectivityObserver::Notify is called with event code

     * EReceivingActivated/EReceivingDeactivated when state change has 

     * completed. While activated incoming data is delivered to the media

     * engine.

     * 

     * Note: If TURN is used media cannot be delivered until remote address

     * is known.

     * 

     * @since   S60 v3.2

     * @pre     FetchCandidate(/s) and possible ICE processing have completed

     * @param   aLocalCandidate The local end point for a media

     * @param   aState          The receiving state

     */

    void SetReceivingStateL( const CNATFWCandidate& aLocalCandidate,

        TNATFWStreamingState aState );

    /**

     * Enables/disables media sending from the specified local candidate.

     * 

     * Only those candidates given with MNATFWConnectivityObserver callbacks

     * can be controlled. NATFW stream can have only one active candidate

     * at a time. In other words, exactly one local candidate can be used

     * for media delivery in receiving, sending or both directions.

     * 

     * Sending must be disabled prior to closing stream so that all

     * resources can be freed.

     * 

     * MNATFWConnectivityObserver::Notify is called with event code

     * ESendingActivated/ESendingDeactivated when state change has 

     * completed. While activated outgoing data from media engine is delivered

     * to the specified remote address.

     * 

     * @since   S60 v3.2

     * @pre     FetchCandidate(/s) and possible ICE processing have completed

     * @param   aLocalCandidate The local end point for a media

     * @param   aState          The sending state

     * @param   aDestAddr       The remote end point for a media

     */

    void SetSendingStateL( const CNATFWCandidate& aLocalCandidate,

        TNATFWStreamingState aState, const TInetAddr& aDestAddr );

    /**

     * Enables/disables media sending in the specified NAT-stream.

     * 

     * MNATFWConnectivityObserver::Notify is called with event code

     * ESendingActivated/ESendingDeactivated when state change has 

     * completed. 

     * 

     * While activated outgoing data from media engine is delivered

     * to the specified FQDN and port.

     * 

     * @since   S60 v3.2

     * @pre     FetchCandidate(/s) and possible ICE processing have completed

     * @param   aLocalCandidate The local end point for a media

     * @param   aState          The streaming state

     * @param   aDestAddr       The destination address for the media as FQDN

     * @param   aPort           The destination port for the media

     */

    void SetSendingStateL( const CNATFWCandidate& aLocalCandidate,

        TNATFWStreamingState aState, const TDesC8& aDestAddr, TUint aPort );

    /**

     * Closes the specified stream.

     *

     * @since   S60 v3.2

     * @pre     Streaming is disabled with SetReceivingStateL/SetSendingStateL

     * @param   aSessionId      The ID identifying session

     * @param   aStreamId       The ID identifying stream

     */

    void CloseStreamL( TUint aSessionId, TUint aStreamId );

    /**

     * Closes the specified session. All streams in the session are

     * closed too.

     *

     * @since   S60 v3.2

     * @pre     Streaming is disabled in all NAT-streams belonging to

     *          the session

     * @param   aSessionId      The ID identifying session

     */

    void CloseSessionL( TUint aSessionId );

    /**

     * From MNcmConnectionMultiplexerObserver.

     * Called by the Multiplexer when actions completes.

     *

     * @since S60 v3.2

     * @param aSessionId    The session identifier

     * @param aStreamId     The stream id where the event occured

     * @param aType         The type of the event

     * @param aError        Error code

     */

    void Notify( TUint aSessionId, TUint aStreamId, TNotifyType aType,

        TInt aError );

    /**

     * From MNATFWRegistrationController.

     * Provides access to the event registry.

     *

     * @since   S60 v3.2

     * @return  The event registry

     */

    const RArray<TNATFWEventRegistration>& Registry();

private:

    CNATFWClient();

    void ConstructL();

    CNATFWSession* SessionByIdL( TUint aSessionId );

    CNATFWStream* FindStreamById( TUint aStreamId );

    void ResolveFQDNAddrL( CNATFWCandidate& aCandidate );

    void DoNotify(

        MNATFWConnectivityObserver::TNATFWConnectivityEvent aEvent,

        TUint aSessionId, TUint aStreamId, TInt aErrCode,

        TAny* aEventData );

private: // data

    /**

     * Pointer to Connection Multiplexer.

     * Own.

     */

    CNcmConnectionMultiplexer* iConnMux;

    /**

     * Events registered by the client

     * Own.

     */

    RArray<TNATFWEventRegistration> iEventRegistry;

    /**

     * Sessions owned by the client

     * Own.

     */

    RPointerArray<CNATFWSession> iSessions;

    /**

     * Async callback handler

     * Own.

     */

    CNatFwAsyncCallback* iAsyncCallback;

    };

#endif // NATFWCLIENT_H