1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:    Implementation classs of the NAT Connectivity FW

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef NATFWCLIENT_H

    22 #define NATFWCLIENT_H

    23 

    24 #include "natfwconnectivityapi.h"

    25 #include "mncmconnectionmultiplexerobserver.h"

    26 #include "mnatfwregistrationcontroller.h"

    27 

    28 class CNcmConnectionMultiplexer;

    29 class MNATFWSocketMediaConnWrapper;

    30 class CNATFWSession;

    31 class CNATFWStream;

    32 class CNatFwAsyncCallback;

    33 

    34 /**

    35  *  The implementation class of the NAT Connectivity FW

    36  *

    37  *  Implemets the NAT connectivity FW API

    38  *

    39  *  @lib natconfw.lib

    40  *  @since S60 v3.2

    41  */

    42 NONSHARABLE_CLASS( CNATFWClient ) : public CBase,

    43     public MNcmConnectionMultiplexerObserver,

    44     public MNATFWRegistrationController

    45     {

    46 

    47     friend class UT_CNATFWClient;

    48 

    49 public:

    50 

    51     static CNATFWClient* NewL();

    52 

    53     static CNATFWClient* NewLC();

    54 

    55     virtual ~CNATFWClient();

    56 

    57     /**

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

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

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

    61      * eventdata.

    62      *

    63      * Refer to MNATFWConnectivityObserver API for event definitions.

    64      *

    65      * @since   S60 v3.2

    66      * @param   aObserver       Observer for NAT Connectivity API events

    67      * @param   aEvents         Events for which to register

    68      * @leave   KErrAlreadyExists Observer is already registered for some of

    69      *  the events

    70      */

    71     void RegisterObserverForEventsL( MNATFWConnectivityObserver& aObserver,

    72         TUint16 aEvents );

    73 

    74     /**

    75      * Unregisters given observer for the specified events.

    76      *

    77      * Refer to MNATFWConnectivityObserver API for event definitions.

    78      *

    79      * @since   S60 v3.2

    80      * @param   aObserver       Observer for NAT Connectivity API events

    81      * @param   aEvents         Events for which to unregister

    82      * @post    Observer will not receive notifications for specified events

    83      *          any more.

    84      */

    85     void UnregisterObserverForEvents( MNATFWConnectivityObserver& aObserver,

    86         TUint16 aEvents );

    87 

    88     /**

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

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

    91      * client receives a callback to MNATFWConnectivityObserver::Notify

    92      * function with event code ESessionCreated.

    93      *

    94      * @since   S60 v3.2

    95      * @param   aIapId          The IAP used for a connection

    96      * @param   aDomain         Used domain for settings query

    97      * @return  The ID for the created session

    98      */

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

   100 

   101     /**

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

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

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

   105      *

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

   107      * working one is found.

   108      *

   109      * @since   S60 v3.2

   110      * @pre     NAT session is created

   111      * @param   aSessionId      The ID identifying session

   112      * @param   aPlugins        Array containing identifiers for available

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

   114      *          "exampleprovider.stun".

   115      * @param   aLoadedPluginInd Index to the aPlugins array telling actually

   116      *  loaded plugin.

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

   118      * @leave   KErrNotFound NAT-plugin was not found

   119      */

   120     void LoadPluginL( TUint aSessionId, const CDesC8Array& aPlugins,

   121         TInt& aLoadedPluginInd );

   122 

   123     /**

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

   125      * stream ID.

   126      *

   127      * @since   S60 v3.2

   128      * @param   aSessionId      The ID identifying session

   129      * @param   aProtocol       KProtocolInetUdp / KProtocolInetTcp

   130      * @param   aQoS            The desired quality of service.

   131      * @return  The ID for the created stream

   132      */

   133     TUint CreateStreamL( TUint aSessionId,

   134         TUint aProtocol, TInt aQoS );

   135 

   136     /**

   137      * Creates a wrapper for the specified stream.

   138      *

   139      * @since   S60 v3.2

   140      * @param   aSessionId      The ID identifying session

   141      * @param   aStreamId       The ID identifying stream

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

   143      */

   144     MNATFWSocketMediaConnWrapper& CreateWrapperL(

   145         TUint aSessionId, TUint aStreamId );

   146 

   147     /**

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

   149      * peers. MNATFWConnectivityObserver::NewLocalCandidateFound

   150      * is called when a public IP has been resolved.

   151      *

   152      * @since   S60 v3.2

   153      * @param   aSessionId      The ID identifying session

   154      * @param   aStreamId       The ID identifying stream

   155      * @param   aAddrFamily     KAFUnspec / KAfInet / KAfInet6

   156      */

   157     void FetchCandidateL( TUint aSessionId, TUint aStreamId,

   158         TUint aAddrFamily );

   159 

   160     /**

   161      * ICE spesific function. Fetches IP address candidates for the

   162      * communication between peers. Client is responsible for providing

   163      * mapping between components of media stream through collection ID

   164      * parameter. MNATFWConnectivityObserver::NewLocalCandidateFound

   165      * is called whenever a new candidate has been found.

   166      *

   167      * @since   S60 v3.2

   168      * @param   aSessionId      The ID identifying session

   169      * @param   aStreamId       The ID identifying stream

   170      * @param   aCollectionId   The stream collection identifier

   171      * @param   aComponentId    The media component identifier

   172      * @param   aAddrFamily     KAFUnspec / KAfInet / KAfInet6

   173      */

   174     void FetchCandidatesL(

   175         TUint aSessionId, TUint aStreamId,

   176         TUint aCollectionId, TUint aComponentId, TUint aAddrFamily );

   177 

   178     /**

   179      * ICE specific function.

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

   181      * will be silently changed.

   182      *

   183      * @since   S60 v3.2

   184      * @param   aSessionId      The ID identifying session

   185      * @param   aRole           The role

   186      */

   187     void SetRoleL( TUint aSessionId, TNATFWIceRole aRole );

   188 

   189     /**

   190      * ICE specific function. Set username fragment and corresponding

   191      * password for message signing and authentication with the specified

   192      * candidate.

   193      *

   194      * @since   S60 v3.2

   195      * @param   aCandidate      The candidate

   196      * @param   aCredentials    The credentials

   197      */

   198     void SetCredentialsL(

   199         CNATFWCandidate& aCandidate,

   200         const CNATFWCredentials& aCredentials );

   201 

   202     /**

   203      * ICE specific function.

   204      * Performs connectivity checks between the local candidates and the

   205      * remote candidates. MNATFWConnectivityObserver::NewCandidatePairFound

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

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

   208      *

   209      * @since   S60 v3.2

   210      * @param   aSessionId      The ID identifying session

   211      * @param   aRemoteCands    The remote candidate array

   212      */

   213     void PerformConnectivityChecksL( TUint aSessionId,

   214         RPointerArray<CNATFWCandidate>& aRemoteCands );

   215 

   216     /**

   217      * ICE specific function.

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

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

   220      * update for that is silently ignored.

   221      *

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

   223      * re-starting connectivity checks with PerformCandidateChecksL.

   224      *

   225      * Adding new streams does not differ from initial operation.

   226      * Removing of streams is handled with CloseStreamL.

   227      *

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

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

   230      *

   231      * @since   S60 v3.2

   232      * @pre     ICE processing is started with PerformConnectivityChecksL

   233      * @param   aSessionId          The ID identifying session

   234      * @param   aPeerSelectedPairs  Peer selected candidate pairs

   235      * @leave   KErrNotSupported Loaded NAT Protocol plugin does not support

   236      * operation.

   237      * @post    ICE processing is continued with new parameters

   238      */

   239     void UpdateIceProcessingL( TUint aSessionId,

   240         RPointerArray<CNATFWCandidatePair>& aPeerSelectedPairs );

   241 

   242     /**

   243      * ICE specific function.

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

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

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

   247      * connectivity tests from this point onwards.

   248      *

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

   250      * re-starting connectivity checks with PerformCandidateChecksL.

   251      *

   252      * Adding new streams does not differ from initial operation.

   253      * Removing of streams is handled with CloseStreamL.

   254      *

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

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

   257      *

   258      * @since   S60 v3.2

   259      * @pre     ICE processing is started with PerformConnectivityChecksL

   260      * @param   aSessionId          The ID identifying session

   261      * @param   aRemoteCands        All remote candidates known currently

   262      * @leave   KErrNotSupported Loaded NAT Protocol plugin does not support

   263      * operation.

   264      * @post    ICE processing is continued with new parameters

   265      */

   266     void UpdateIceProcessingL( TUint aSessionId,

   267         RPointerArray<CNATFWCandidate>& aRemoteCands );

   268 

   269     /**

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

   271      * 

   272      * Only those candidates given with MNATFWConnectivityObserver callbacks

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

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

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

   276      * 

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

   278      * resources can be freed.

   279      * 

   280      * MNATFWConnectivityObserver::Notify is called with event code

   281      * EReceivingActivated/EReceivingDeactivated when state change has 

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

   283      * engine.

   284      * 

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

   286      * is known.

   287      * 

   288      * @since   S60 v3.2

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

   290      * @param   aLocalCandidate The local end point for a media

   291      * @param   aState          The receiving state

   292      */

   293     void SetReceivingStateL( const CNATFWCandidate& aLocalCandidate,

   294         TNATFWStreamingState aState );

   295 

   296     /**

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

   298      * 

   299      * Only those candidates given with MNATFWConnectivityObserver callbacks

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

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

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

   303      * 

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

   305      * resources can be freed.

   306      * 

   307      * MNATFWConnectivityObserver::Notify is called with event code

   308      * ESendingActivated/ESendingDeactivated when state change has 

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

   310      * to the specified remote address.

   311      * 

   312      * @since   S60 v3.2

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

   314      * @param   aLocalCandidate The local end point for a media

   315      * @param   aState          The sending state

   316      * @param   aDestAddr       The remote end point for a media

   317      */

   318     void SetSendingStateL( const CNATFWCandidate& aLocalCandidate,

   319         TNATFWStreamingState aState, const TInetAddr& aDestAddr );

   320 

   321     /**

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

   323      * 

   324      * MNATFWConnectivityObserver::Notify is called with event code

   325      * ESendingActivated/ESendingDeactivated when state change has 

   326      * completed. 

   327      * 

   328      * While activated outgoing data from media engine is delivered

   329      * to the specified FQDN and port.

   330      * 

   331      * @since   S60 v3.2

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

   333      * @param   aLocalCandidate The local end point for a media

   334      * @param   aState          The streaming state

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

   336      * @param   aPort           The destination port for the media

   337      */

   338     void SetSendingStateL( const CNATFWCandidate& aLocalCandidate,

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

   340 

   341     /**

   342      * Closes the specified stream.

   343      *

   344      * @since   S60 v3.2

   345      * @pre     Streaming is disabled with SetReceivingStateL/SetSendingStateL

   346      * @param   aSessionId      The ID identifying session

   347      * @param   aStreamId       The ID identifying stream

   348      */

   349     void CloseStreamL( TUint aSessionId, TUint aStreamId );

   350 

   351     /**

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

   353      * closed too.

   354      *

   355      * @since   S60 v3.2

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

   357      *          the session

   358      * @param   aSessionId      The ID identifying session

   359      */

   360     void CloseSessionL( TUint aSessionId );

   361 

   362     /**

   363      * From MNcmConnectionMultiplexerObserver.

   364      * Called by the Multiplexer when actions completes.

   365      *

   366      * @since S60 v3.2

   367      * @param aSessionId    The session identifier

   368      * @param aStreamId     The stream id where the event occured

   369      * @param aType         The type of the event

   370      * @param aError        Error code

   371      */

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

   373         TInt aError );

   374 

   375     /**

   376      * From MNATFWRegistrationController.

   377      * Provides access to the event registry.

   378      *

   379      * @since   S60 v3.2

   380      * @return  The event registry

   381      */

   382     const RArray<TNATFWEventRegistration>& Registry();

   383 

   384 private:

   385 

   386     CNATFWClient();

   387 

   388     void ConstructL();

   389 

   390     CNATFWSession* SessionByIdL( TUint aSessionId );

   391 

   392     CNATFWStream* FindStreamById( TUint aStreamId );

   393 

   394     void ResolveFQDNAddrL( CNATFWCandidate& aCandidate );

   395 

   396     void DoNotify(

   397         MNATFWConnectivityObserver::TNATFWConnectivityEvent aEvent,

   398         TUint aSessionId, TUint aStreamId, TInt aErrCode,

   399         TAny* aEventData );

   400 

   401 private: // data

   402 

   403     /**

   404      * Pointer to Connection Multiplexer.

   405      * Own.

   406      */

   407     CNcmConnectionMultiplexer* iConnMux;

   408 

   409     /**

   410      * Events registered by the client

   411      * Own.

   412      */

   413     RArray<TNATFWEventRegistration> iEventRegistry;

   414 

   415     /**

   416      * Sessions owned by the client

   417      * Own.

   418      */

   419     RPointerArray<CNATFWSession> iSessions;

   420 

   421     /**

   422      * Async callback handler

   423      * Own.

   424      */

   425     CNatFwAsyncCallback* iAsyncCallback;

   426 

   427     };

   428 

   429 #endif // NATFWCLIENT_H