1 /*

     2 * Copyright (c) 2006-2008 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:    API for NAT protocol plug-ins

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef C_CNATFWPLUGINAPI_H

    22 #define C_CNATFWPLUGINAPI_H

    23 

    24 

    25 #include <e32base.h>

    26 #include <ecom/ecom.h>

    27 #include <in_sock.h>

    28 #include "natfwconnectivityapidefs.h"

    29 

    30 

    31 class MNATFWPluginObserver;

    32 class CNATFWCandidate;

    33 class CNATFWCredentials;

    34 class MNcmConnectionMultiplexer;

    35 class CNATFWCandidatePair;

    36 

    37 

    38 /** NAT protocol plugin interface UID */

    39 const TUid KInterfaceUid = { 0x10275444 };

    40 

    41 /**

    42  *  Interface for the NAT protocol plug-ins.

    43  *

    44  *  @lib natfwclient.lib

    45  *  @since S60 v3.2 

    46  */

    47 class CNATFWPluginApi : public CBase

    48     {

    49 

    50 public:

    51 

    52     /**

    53      *  Class encapsulates initialization parameters needed in plugin

    54      *  instantiation.

    55      *

    56      *  @lib natfwclient.lib

    57      *  @since S60 v3.2 

    58      */

    59     class TNATFWPluginInitParams

    60         {

    61         public:

    62 

    63             /**

    64              * Constructor.

    65              * @param aObserver     The observer for NAT-plugin

    66              * @param aMultiplexer  The multiplexer

    67              * @param aDomain       The domain where to operate

    68              * @param iIapId        The Internet access point identifier

    69              */

    70             TNATFWPluginInitParams( MNATFWPluginObserver& aObserver,

    71                 MNcmConnectionMultiplexer& aMultiplexer,

    72                 const TDesC8& aDomain, TUint32 iIapId );

    73 

    74         public:

    75                     

    76             MNATFWPluginObserver& iObserver;

    77             MNcmConnectionMultiplexer& iMultiplexer;

    78             const TDesC8& iDomain;

    79             TUint32 iIapId;

    80         };

    81 

    82 

    83     /**

    84      * Two-phased constructor.

    85      * @param aImplementationUid    Implementation UID of the plugin to load

    86      * @param aInitParams           Initialization parameters

    87      */

    88     static CNATFWPluginApi* NewL( 

    89         TUid aImplementationUid,

    90         TNATFWPluginInitParams& aInitParams );

    91 

    92     /**

    93      * Two-phased constructor.

    94      * @param aPluginId             Identifier of the plugin to load

    95      * @param aInitParams           Initialization parameters

    96      */

    97     static CNATFWPluginApi* NewL( 

    98         const TDesC8& aPluginId,

    99         TNATFWPluginInitParams& aInitParams );

   100 

   101     /**

   102      * Destructor.

   103      */

   104     virtual ~CNATFWPluginApi();

   105 

   106     /**

   107      * Lists all available NAT-protocol plugin implementations.

   108      *

   109      * @since   S60 v3.2

   110      * @param   aImplInfoArray      Array of implementations

   111      */

   112     static void ListAllImplementationsL( RImplInfoPtrArray& aImplInfoArray );

   113 

   114     /**

   115      * Finds out a STUN Server and establishes a connection to it.

   116      * 

   117      * MNATFWPluginObserver::Notify is called with event code EServerConnected

   118      * when connecting has completed.

   119      *     

   120      * FetchCandidateL can be called after successful connecting.

   121      *

   122      * @since   S60 v3.2

   123      * @param   aSocketServ         The handle to socket server session

   124      * @param   aConnectionName     The unique name of the RConnection

   125      * @return  void

   126      */

   127     virtual void ConnectServerL( const RSocketServ& aSocketServ,

   128         const TName& aConnectionName ) = 0;

   129     

   130     /**

   131      * Fetches available candidates for a specified stream using given

   132      * retransmission timeout for STUN transactions. 

   133      * 

   134      * RTO value 0 indicates default retransmission timeout as specified

   135      * in STUN specification.

   136      * 

   137      * @since   S60 v3.2

   138      * @param   aStreamId           Stream identifier

   139      * @param   aRtoValue           Retransmission timeout in milliseconds

   140      * @param   aAddrFamily         KAFUnspec / KAfInet / KAfInet6

   141      * @leave   KErrNotSupported NAT Protocol plugin does not support

   142      * operation.

   143      */

   144     virtual inline void FetchCandidateL( TUint aStreamId, TUint aRtoValue,

   145         TUint aAddrFamily );

   146     

   147     /**

   148      * Fetches available candidates for a specified stream using given

   149      * retransmission timeout for STUN transactions. 

   150      * 

   151      * RTO value 0 indicates default retransmission timeout as specified

   152      * in STUN specification.

   153      * 

   154      * Candidate is fetched using given base address as a local endpoint for

   155      * a multiplexer connection.

   156      * 

   157      * @since   S60 v3.2

   158      * @param   aStreamId           Stream identifier

   159      * @param   aRtoValue           Retransmission timeout in milliseconds

   160      * @param   aBaseAddr           Address from which to create connection

   161      */

   162     virtual inline void FetchCandidateL( TUint aStreamId, TUint aRtoValue,

   163         const TInetAddr& aBaseAddr );

   164     

   165     /**

   166      * ICE specific function.

   167      * Fetches all available candidates for a specified stream in a 

   168      * stream collection.

   169      *

   170      * @since   S60 v3.2

   171      * @param   aStreamCollectionId Stream collection identifier

   172      * @param   aStreamId           Stream identifier

   173      * @param   aComponentId        Component identifier

   174      * @param   aAddrFamily         KAFUnspec / KAfInet / KAfInet6

   175      * @leave   KErrNotSupported NAT Protocol plugin does not support

   176      * operation.

   177      */

   178     virtual inline void FetchCandidatesL( TUint aStreamCollectionId,

   179         TUint aStreamId, TUint aComponentId, TUint aAddrFamily );

   180     

   181     /**

   182      * ICE specific function.

   183      * Sets the role for ICE. In role-conflict situation given role

   184      * will be silently changed.

   185      *

   186      * @since   S60 v3.2

   187      * @param   aRole               The role

   188      * @leave   KErrNotSupported NAT Protocol plugin does not support

   189      * operation.

   190      */

   191     virtual inline void SetRoleL( TNATFWIceRole aRole );

   192 

   193     /**

   194      * ICE specific function. 

   195      * Sets username fragment and corresponding password for message signing

   196      * and authentication with the specified candidate.

   197      *

   198      * @since   S60 v3.2

   199      * @param   aCandidate          The candidate

   200      * @param   aCredentials        The credentials

   201      * @leave   KErrNotSupported NAT Protocol plugin does not support

   202      * operation.

   203      */

   204     virtual inline void SetCredentialsL(

   205         const CNATFWCandidate& aCandidate,

   206         const CNATFWCredentials& aCredentials );

   207 

   208     /**

   209      * ICE specific function.

   210      * Starts to perform connectivity checks.

   211      *

   212      * @since   S60 v3.2

   213      * @param   aRemoteCandidates   Remote candidate array

   214      * @leave   KErrNotSupported NAT Protocol plugin does not support

   215      * operation.

   216      */

   217     virtual inline void PerformConnectivityChecksL( 

   218         RPointerArray<CNATFWCandidate>& aRemoteCandidates );

   219 

   220     /**

   221      * ICE specific function.

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

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

   224      * update for that is silently ignored.

   225      * 

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

   227      * re-starting connectivity checks with PerformCandidateChecksL.

   228      * 

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

   230      * Removing of streams is handled with CloseStreamL.

   231      * 

   232      * @since   S60 v3.2

   233      * @pre     ICE processing is started with PerformConnectivityChecksL

   234      * @param   aPeerSelectedPairs  Peer selected candidate pairs

   235      * @leave   KErrNotSupported NAT Protocol plugin does not support

   236      * operation.

   237      * @post    ICE processing is continued with new parameters

   238      */

   239     virtual inline void UpdateIceProcessingL( 

   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      * @since   S60 v3.2

   256      * @pre     ICE processing is started with PerformConnectivityChecksL

   257      * @param   aRemoteCands        All remote candidates known currently

   258      * @leave   KErrNotSupported NAT Protocol plugin does not support

   259      * operation.

   260      * @post    ICE processing is continued with new parameters

   261      */

   262     virtual inline void UpdateIceProcessingL( 

   263         RPointerArray<CNATFWCandidate>& aRemoteCands );

   264     

   265     /**

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

   267      * 

   268      * Only those candidates given with MNATFWPluginObserver callbacks

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

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

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

   272      * 

   273      * MNATFWPluginObserver::Notify is called with event code

   274      * EReceivingActivated/EReceivingDeactivated when status change has 

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

   276      * engine.

   277      * 

   278      * Receiving must be disabled prior to deleting plugin so that all

   279      * resources can be freed.

   280      * 

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

   282      * is known.

   283      * 

   284      * @since   S60 v3.2

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

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

   287      * @param   aState          The receiving state

   288      */

   289     virtual void SetReceivingStateL( const CNATFWCandidate& aLocalCandidate,

   290         TNATFWStreamingState aState ) = 0;

   291     

   292     /**

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

   294      * 

   295      * Only those candidates given with MNATFWPluginObserver callbacks

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

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

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

   299      * 

   300      * Sending must be disabled prior to deleting plugin so that all

   301      * resources can be freed.

   302      * 

   303      * MNATFWPluginObserver::Notify is called with event code

   304      * ESendingActivated/ESendingDeactivated when status change has 

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

   306      * to the specified remote address.

   307      * 

   308      * @since   S60 v3.2

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

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

   311      * @param   aState          The sending state

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

   313      */

   314     virtual void SetSendingStateL( const CNATFWCandidate& aLocalCandidate,

   315         TNATFWStreamingState aState, const TInetAddr& aDestAddr ) = 0;

   316     

   317     /**

   318      * Gets identifier for a connection that is associated with the

   319      * given local end point.

   320      * 

   321      * @since   S60 v3.2

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

   323      * @param   aConnectionId       Reference to found id

   324      */

   325     virtual void GetConnectionIdL( 

   326         const CNATFWCandidate& aLocalCandidate,

   327         TUint& aConnectionId ) = 0;

   328     

   329     /**

   330      * Get identifier of the plugin.

   331      * 

   332      * @since   S60 v3.2

   333      * @return  Identifier of the plugin

   334      */

   335     virtual const TDesC8& PluginIdentifier() const = 0;

   336 

   337 protected:

   338 

   339     inline CNATFWPluginApi();

   340 

   341 private:

   342 

   343     void ConstructL();

   344 

   345 private: // data

   346 

   347     /**

   348      * Unique instance identifier key

   349      */

   350     TUid iDtor_ID_Key;

   351     };

   352 

   353 

   354 #include "natfwpluginapi.inl"

   355 

   356 

   357 #endif // C_CNATFWPLUGINAPI_H