/*
* 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