1 /*

     2 * Copyright (c) 2007 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:    NAT FW session abstraction

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef C_CNATFWSESSION_H

    22 #define C_CNATFWSESSION_H

    23 

    24 #include <e32base.h>

    25 #include "natfwconnectivityapidefs.h"

    26 #include "mnatfwpluginobserver.h"

    27 

    28 class CNATFWCandidate;

    29 class CNATFWCandidatePair;

    30 class CNATFWStream;

    31 class CNcmConnectionMultiplexer;

    32 class MNATFWConnectivityObserver;

    33 class MNATFWRegistrationController;

    34 class CNATFWPluginApi;

    35 class CNATFWNatSettingsApi;

    36 class CNATFWPluginApi;

    37 class CDesC8Array;

    38 class CNatFwAsyncCallback;

    39 

    40 /**

    41  *  NAT FW session abstraction.

    42  *

    43  *  Provides network connection layer and operation context for

    44  *  the NAT FW streams. Can be mapped e.g. to the SDP-session.

    45  *

    46  *  @lib natconfw.lib

    47  *  @since S60 v3.2

    48  */

    49 NONSHARABLE_CLASS( CNATFWSession ) : public CBase, public MNATFWPluginObserver

    50     {

    51 

    52     friend class UT_CNATFWClient;

    53 

    54 public:

    55 

    56     static CNATFWSession* NewL(

    57         CNcmConnectionMultiplexer& aMultiplexer,

    58         MNATFWRegistrationController& aController,

    59         CNatFwAsyncCallback& aAsyncCallback,

    60         const TDesC8& aDomain,

    61         TUint32 aIapId );

    62 

    63     static CNATFWSession* NewLC(

    64         CNcmConnectionMultiplexer& aMultiplexer,

    65         MNATFWRegistrationController& aController,

    66         CNatFwAsyncCallback& aAsyncCallback,

    67         const TDesC8& aDomain,

    68         TUint32 aIapId );

    69 

    70     virtual ~CNATFWSession();

    71 

    72     /**

    73      * Returns the session identifier.

    74      *

    75      * @since   S60 v3.2

    76      * @return  The session identifier

    77      */

    78     TUint SessionId() const;

    79 

    80     /**

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

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

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

    84      *

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

    86      * working one is found.

    87      *

    88      * @since   S60 v3.2

    89      * @param   aPlugins        Array containing identifiers for available

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

    91      *          "exampleprovider.stun".

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

    93      *          loaded plugin.

    94      * @leave   KErrNotFound NAT-plugin was not found

    95      */

    96     void LoadPluginL( const CDesC8Array& aPlugins, TInt& aLoadedPluginInd );

    97 

    98 

    99     /**

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

   101      * peers. MNATFWConnectivityObserver::NewLocalCandidateFound

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

   103      *

   104      * @since   S60 v3.2

   105      * @param   aStreamId       The ID identifying stream

   106      * @param   aAddrFamily     KAFUnspec / KAfInet / KAfInet6

   107      */

   108     void FetchCandidateL( TUint aStreamId, TUint aAddrFamily );

   109     

   110     /**

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

   112      * communication between peers. Client is responsible for providing a

   113      * mapping between components of media stream through the collection ID

   114      * parameter. MNATFWConnectivityObserver::NewLocalCandidateFound

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

   116      *

   117      * @since   S60 v3.2

   118      * @param   aStreamId       The ID identifying stream

   119      * @param   aCollectionId   The stream collection identifier

   120      * @param   aComponentId    The media component identifier

   121      * @param   aAddrFamily     KAFUnspec / KAfInet / KAfInet6

   122      */

   123     void FetchCandidatesL( TUint aStreamId, TUint aCollectionId,

   124         TUint aComponentId, TUint aAddrFamily );

   125            

   126     /**

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

   128      * stream identifier.

   129      *

   130      * @since   S60 v3.2

   131      * @param   aProtocol       KProtocolInetUdp / KProtocolInetTcp

   132      * @param   aQoS            The desired quality of service.

   133      * @return  The ID for the created stream

   134      */

   135     TUint CreateStreamL( TUint aProtocol, TInt aQoS );

   136 

   137     /**

   138      * ICE specific function.

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

   140      * will be silently changed.

   141      *

   142      * @since   S60 v3.2

   143      * @param   aRole           The role

   144      */

   145     void SetRoleL( TNATFWIceRole aRole );

   146 

   147     /**

   148      * ICE specific function.

   149      * Performs connectivity checks between the local candidates and the

   150      * remote candidates. MNATFWConnectivityObserver::NewCandidatePairFound

   151      * is called whenever working connection between local and remote

   152      * candidate is found.

   153      *

   154      * @since   S60 v3.2

   155      * @param   aRemoteCandidates   The remote candidate array

   156      */

   157     void PerformConnectivityChecksL(

   158         RPointerArray<CNATFWCandidate>& aRemoteCandidates );

   159 

   160     /**

   161      * ICE specific function.

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

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

   164      * update for that is silently ignored.

   165      *

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

   167      * re-starting connectivity checks with PerformCandidateChecksL.

   168      *

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

   170      * Removing of streams is handled with CloseStreamL.

   171      *

   172      * @since   S60 v3.2

   173      * @pre     ICE processing is started with PerformConnectivityChecksL

   174      * @param   aPeerSelectedPairs  Peer selected candidate pairs

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

   176      * operation.

   177      * @post    ICE processing is continued with new parameters

   178      */

   179     void UpdateIceProcessingL(

   180         RPointerArray<CNATFWCandidatePair>& aPeerSelectedPairs );

   181 

   182     /**

   183      * ICE specific function.

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

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

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

   187      * connectivity tests from this point onwards.

   188      *

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

   190      * re-starting connectivity checks with PerformCandidateChecksL.

   191      *

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

   193      * Removing of streams is handled with CloseStreamL.

   194      *

   195      * @since   S60 v3.2

   196      * @pre     ICE processing is started with PerformConnectivityChecksL

   197      * @param   aRemoteCands        All remote candidates known currently

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

   199      * operation.

   200      * @post    ICE processing is continued with new parameters

   201      */

   202     void UpdateIceProcessingL(

   203         RPointerArray<CNATFWCandidate>& aRemoteCands );

   204 

   205     /**

   206      * Closes the stream from the session.

   207      *

   208      * @since   S60 v3.2

   209      * @pre     Streaming is disabled with SetReceivingStateL/SetSendingStateL

   210      * @param   aStreamId           The ID identifying stream

   211      */

   212     void CloseStreamL( TUint aStreamId );

   213 

   214     /**

   215      * Returns stream by identifier.

   216      *

   217      * @since   S60 v3.2

   218      * @param   aStreamId           The ID identifying stream

   219      * @return  Stream or NULL if not found

   220      */

   221     CNATFWStream* StreamById( TUint aStreamId );

   222 

   223     /**

   224      * Returns stream by identifier. Leaves with KErrNotFound if stream

   225      * isn't found.

   226      *

   227      * @since   S60 v3.2

   228      * @param   aStreamId           The ID identifying stream

   229      * @return  Stream

   230      */

   231     CNATFWStream* StreamByIdL( TUint aStreamId );

   232 

   233     /**

   234      * From MNATFWPluginObserver.

   235      * Called when an error within a stream has occured.

   236      *

   237      * @since   S60 v3.2

   238      * @param   aPlugin         The plugin raising event

   239      * @param   aStreamId       The ID identifying stream

   240      * @param   aErrorCode      Standard system wide error code

   241      */

   242     void Error( const CNATFWPluginApi& aPlugin,

   243         TUint aStreamId, TInt aErrorCode );

   244 

   245     /**

   246      * From MNATFWPluginObserver.

   247      * Notifies the client of plugin events.

   248      *

   249      * @since   S60 v3.2

   250      * @param   aPlugin         The plugin raising event

   251      * @param   aStreamId       The ID identifying stream

   252      * @param   aEvent          The event

   253      * @param   aErrCode        Standard system wide error code

   254      */

   255     void Notify( const CNATFWPluginApi& aPlugin,

   256         TUint aStreamId, TNATFWPluginEvent aEvent, TInt aErrCode );

   257 

   258     /**

   259      * From MNATFWPluginObserver.

   260      * Called when working candidate pair has been found. Ownership of

   261      * the candidate pair is trasferred.

   262      *

   263      * @since   S60 v3.2

   264      * @param   aPlugin         The plugin raising event

   265      * @param   aCandidatePair  The candidate pair which was found

   266      */

   267     void NewCandidatePairFound(

   268         const CNATFWPluginApi& aPlugin,

   269         CNATFWCandidatePair* aCandidatePair );

   270 

   271     /**

   272      * From MNATFWPluginObserver.

   273      * Called when a new local candidate has been found. Ownership of the

   274      * candidate is trasferred.

   275      *

   276      * @since   S60 v3.2

   277      * @param   aPlugin         The plugin raising event

   278      * @param   aCandidate      The local candidate that was found

   279      */

   280     void NewLocalCandidateFound(

   281         const CNATFWPluginApi& aPlugin,

   282         CNATFWCandidate* aCandidate );

   283 

   284 private:

   285 

   286     CNATFWSession(

   287         CNcmConnectionMultiplexer& aMultiplexer,

   288         MNATFWRegistrationController& aController,

   289         CNatFwAsyncCallback& aAsyncCallback,

   290         TUint32 aIapId );

   291 

   292     void ConstructL( const TDesC8& aDomain );

   293 

   294     void HandleQueuedItems();

   295 

   296     void DoNotify(

   297         TUint aStreamId,

   298         MNATFWConnectivityObserver::TNATFWConnectivityEvent aEvent,

   299         TInt aErrCode,

   300         TAny* aEventData );

   301 

   302 private:

   303 

   304     /** Identifies states for Server connection  **/

   305     enum TServerConnectionState

   306         {

   307         EConnectionUnspecified    =   1,

   308         EConnectionInProgress     =   2,

   309         EConnectionConnected      =   3,

   310         EConnectionFailed         =   4

   311         };

   312 

   313     class TStatusCounter

   314         {

   315     public: // Constructors and destructor

   316 

   317     inline TStatusCounter() :

   318         iActivatedCount( 0 ),

   319         iStreamId( 0 ),

   320         iErrorOccurred( EFalse )

   321         {};

   322 

   323     public: // Data

   324 

   325         TUint iActivatedCount;

   326 

   327         TUint iStreamId;

   328 

   329         TBool iErrorOccurred;

   330         };

   331 

   332 

   333     class TFetchingData

   334         {

   335     public: // Constructors and destructor

   336 

   337     inline TFetchingData( TUint aStreamId, TUint aCollectionId,

   338             TUint aComponentId, TUint aAddrFamily, TBool aICESpecific ) :

   339         iStreamId( aStreamId ),

   340         iCollectionId( aCollectionId ),

   341         iComponentId( aComponentId ),

   342         iAddrFamily( aAddrFamily ),

   343         iICESpecific( aICESpecific )

   344         {};

   345 

   346     public: // Data

   347 

   348         TUint iStreamId;

   349         TUint iCollectionId;

   350         TUint iComponentId;

   351         TUint iAddrFamily;

   352         TBool iICESpecific;

   353         };

   354 

   355 private: // data

   356 

   357     /**

   358      * Used to keep track ongoing sending status requests on stream basis.

   359      * Own.

   360      */

   361     RArray<TStatusCounter> iSendingStatusCounts;

   362 

   363     /**

   364      * Used to keep track ongoing receiving status requests on stream basis.

   365      * Own.

   366      */

   367     RArray<TStatusCounter> iReceivingStatusCounts;

   368 

   369     /**

   370      * Unique session identifier

   371      */

   372     TUint iSessionId;

   373 

   374     /**

   375      * Internet access point identifier

   376      */

   377     TUint32 iIapId;

   378 

   379     /**

   380      * Domain for settings querying

   381      * Own.

   382      */

   383     HBufC8* iDomain;

   384 

   385     /**

   386      * NAT FW Registration controller

   387      * Not own.

   388      */

   389     MNATFWRegistrationController& iController;

   390 

   391     /**

   392      * The multiplexer

   393      * Not own.

   394      */

   395     CNcmConnectionMultiplexer& iMultiplexer;

   396 

   397     /**

   398      * Async callback handler

   399      * Not own.

   400      */

   401     CNatFwAsyncCallback& iAsyncCallback;

   402 

   403     /**

   404      * NAT-settings

   405      * Own.

   406      */

   407     CNATFWNatSettingsApi* iNatSettings;

   408 

   409     /**

   410      * NAT-protocol plugin used in the session

   411      * Own.

   412      */

   413     CNATFWPluginApi* iPlugin;

   414 

   415     /**

   416      * Streams created into the session

   417      * Own.

   418      */

   419     RPointerArray<CNATFWStream> iStreams;

   420 

   421     /**

   422      * Server connection process state

   423      */

   424     TServerConnectionState iServerConnectionState;

   425 

   426     /**

   427      * FetchCandidate(s) queue

   428      * Own.

   429      */

   430     RArray<TFetchingData> iFetchCandidateQueue;

   431 

   432     };

   433 

   434 #endif // C_CNATFWSESSION_H