/*
* Copyright (c) 2006-2008 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: API for NAT protocol plug-ins
*
*/
#ifndef C_CNATFWPLUGINAPI_H
#define C_CNATFWPLUGINAPI_H
#include <e32base.h>
#include <ecom/ecom.h>
#include <in_sock.h>
#include "natfwconnectivityapidefs.h"
class MNATFWPluginObserver;
class CNATFWCandidate;
class CNATFWCredentials;
class MNcmConnectionMultiplexer;
class CNATFWCandidatePair;
/** NAT protocol plugin interface UID */
const TUid KInterfaceUid = { 0x10275444 };
/**
* Interface for the NAT protocol plug-ins.
*
* @lib natfwclient.lib
* @since S60 v3.2
*/
class CNATFWPluginApi : public CBase
{
public:
/**
* Class encapsulates initialization parameters needed in plugin
* instantiation.
*
* @lib natfwclient.lib
* @since S60 v3.2
*/
class TNATFWPluginInitParams
{
public:
/**
* Constructor.
* @param aObserver The observer for NAT-plugin
* @param aMultiplexer The multiplexer
* @param aDomain The domain where to operate
* @param iIapId The Internet access point identifier
*/
TNATFWPluginInitParams( MNATFWPluginObserver& aObserver,
MNcmConnectionMultiplexer& aMultiplexer,
const TDesC8& aDomain, TUint32 iIapId );
public:
MNATFWPluginObserver& iObserver;
MNcmConnectionMultiplexer& iMultiplexer;
const TDesC8& iDomain;
TUint32 iIapId;
};
/**
* Two-phased constructor.
* @param aImplementationUid Implementation UID of the plugin to load
* @param aInitParams Initialization parameters
*/
static CNATFWPluginApi* NewL(
TUid aImplementationUid,
TNATFWPluginInitParams& aInitParams );
/**
* Two-phased constructor.
* @param aPluginId Identifier of the plugin to load
* @param aInitParams Initialization parameters
*/
static CNATFWPluginApi* NewL(
const TDesC8& aPluginId,
TNATFWPluginInitParams& aInitParams );
/**
* Destructor.
*/
virtual ~CNATFWPluginApi();
/**
* Lists all available NAT-protocol plugin implementations.
*
* @since S60 v3.2
* @param aImplInfoArray Array of implementations
*/
static void ListAllImplementationsL( RImplInfoPtrArray& aImplInfoArray );
/**
* Finds out a STUN Server and establishes a connection to it.
*
* MNATFWPluginObserver::Notify is called with event code EServerConnected
* when connecting has completed.
*
* FetchCandidateL can be called after successful connecting.
*
* @since S60 v3.2
* @param aSocketServ The handle to socket server session
* @param aConnectionName The unique name of the RConnection
* @return void
*/
virtual void ConnectServerL( const RSocketServ& aSocketServ,
const TName& aConnectionName ) = 0;
/**
* Fetches available candidates for a specified stream using given
* retransmission timeout for STUN transactions.
*
* RTO value 0 indicates default retransmission timeout as specified
* in STUN specification.
*
* @since S60 v3.2
* @param aStreamId Stream identifier
* @param aRtoValue Retransmission timeout in milliseconds
* @param aAddrFamily KAFUnspec / KAfInet / KAfInet6
* @leave KErrNotSupported NAT Protocol plugin does not support
* operation.
*/
virtual inline void FetchCandidateL( TUint aStreamId, TUint aRtoValue,
TUint aAddrFamily );
/**
* Fetches available candidates for a specified stream using given
* retransmission timeout for STUN transactions.
*
* RTO value 0 indicates default retransmission timeout as specified
* in STUN specification.
*
* Candidate is fetched using given base address as a local endpoint for
* a multiplexer connection.
*
* @since S60 v3.2
* @param aStreamId Stream identifier
* @param aRtoValue Retransmission timeout in milliseconds
* @param aBaseAddr Address from which to create connection
*/
virtual inline void FetchCandidateL( TUint aStreamId, TUint aRtoValue,
const TInetAddr& aBaseAddr );
/**
* ICE specific function.
* Fetches all available candidates for a specified stream in a
* stream collection.
*
* @since S60 v3.2
* @param aStreamCollectionId Stream collection identifier
* @param aStreamId Stream identifier
* @param aComponentId Component identifier
* @param aAddrFamily KAFUnspec / KAfInet / KAfInet6
* @leave KErrNotSupported NAT Protocol plugin does not support
* operation.
*/
virtual inline void FetchCandidatesL( TUint aStreamCollectionId,
TUint aStreamId, TUint aComponentId, TUint aAddrFamily );
/**
* ICE specific function.
* Sets the role for ICE. In role-conflict situation given role
* will be silently changed.
*
* @since S60 v3.2
* @param aRole The role
* @leave KErrNotSupported NAT Protocol plugin does not support
* operation.
*/
virtual inline void SetRoleL( TNATFWIceRole aRole );
/**
* ICE specific function.
* Sets 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
* @leave KErrNotSupported NAT Protocol plugin does not support
* operation.
*/
virtual inline void SetCredentialsL(
const CNATFWCandidate& aCandidate,
const CNATFWCredentials& aCredentials );
/**
* ICE specific function.
* Starts to perform connectivity checks.
*
* @since S60 v3.2
* @param aRemoteCandidates Remote candidate array
* @leave KErrNotSupported NAT Protocol plugin does not support
* operation.
*/
virtual inline void PerformConnectivityChecksL(
RPointerArray<CNATFWCandidate>& aRemoteCandidates );
/**
* 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.
*
* @since S60 v3.2
* @pre ICE processing is started with PerformConnectivityChecksL
* @param aPeerSelectedPairs Peer selected candidate pairs
* @leave KErrNotSupported NAT Protocol plugin does not support
* operation.
* @post ICE processing is continued with new parameters
*/
virtual inline void UpdateIceProcessingL(
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.
*
* @since S60 v3.2
* @pre ICE processing is started with PerformConnectivityChecksL
* @param aRemoteCands All remote candidates known currently
* @leave KErrNotSupported NAT Protocol plugin does not support
* operation.
* @post ICE processing is continued with new parameters
*/
virtual inline void UpdateIceProcessingL(
RPointerArray<CNATFWCandidate>& aRemoteCands );
/**
* Enables/disables media receiving for the specified local candidate.
*
* Only those candidates given with MNATFWPluginObserver 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.
*
* MNATFWPluginObserver::Notify is called with event code
* EReceivingActivated/EReceivingDeactivated when status change has
* completed. While activated incoming data is delivered to the media
* engine.
*
* Receiving must be disabled prior to deleting plugin so that all
* resources can be freed.
*
* 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
*/
virtual void SetReceivingStateL( const CNATFWCandidate& aLocalCandidate,
TNATFWStreamingState aState ) = 0;
/**
* Enables/disables media sending from the specified local candidate.
*
* Only those candidates given with MNATFWPluginObserver 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 deleting plugin so that all
* resources can be freed.
*
* MNATFWPluginObserver::Notify is called with event code
* ESendingActivated/ESendingDeactivated when status 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
*/
virtual void SetSendingStateL( const CNATFWCandidate& aLocalCandidate,
TNATFWStreamingState aState, const TInetAddr& aDestAddr ) = 0;
/**
* Gets identifier for a connection that is associated with the
* given local end point.
*
* @since S60 v3.2
* @param aLocalCandidate The local end point for a media
* @param aConnectionId Reference to found id
*/
virtual void GetConnectionIdL(
const CNATFWCandidate& aLocalCandidate,
TUint& aConnectionId ) = 0;
/**
* Get identifier of the plugin.
*
* @since S60 v3.2
* @return Identifier of the plugin
*/
virtual const TDesC8& PluginIdentifier() const = 0;
protected:
inline CNATFWPluginApi();
private:
void ConstructL();
private: // data
/**
* Unique instance identifier key
*/
TUid iDtor_ID_Key;
};
#include "natfwpluginapi.inl"
#endif // C_CNATFWPLUGINAPI_H