1 /*

     2 * Copyright (c) 2006-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:    Provides services for client to traverse NATs

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 

    22 #ifndef NATCONNECTIVITYFW_H

    23 #define NATCONNECTIVITYFW_H

    24 

    25 #include <e32base.h>

    26 #include <in_sock.h>

    27 #include "natfwconnectivityapidefs.h"

    28 

    29 class CNATFWClient;

    30 class MNATFWSocketMediaConnWrapper;

    31 class CNATFWCandidate;

    32 class CNATFWCredentials;

    33 class MNATFWConnectivityObserver;

    34 class CDesC8Array;

    35 class CNATFWCandidatePair;

    36 

    37 /**

    38  * Main API to the NAT Connectivity Framework. Provides services for client

    39  * to traverse through NATs and firewalls.

    40  *

    41  * Only one API instance per client is intended to create.

    42  *

    43  * @lib natconfw.lib

    44  * @since S60 v3.2

    45  */

    46 class CNATFWConnectivityApi : public CBase

    47     {

    48 

    49 public:

    50 

    51     /**

    52      * Two-phased constructor.

    53      */

    54     IMPORT_C static CNATFWConnectivityApi* NewL();

    55 

    56     /**

    57      * Two-phased constructor.

    58      */

    59     IMPORT_C static CNATFWConnectivityApi* NewLC();

    60 

    61     /**

    62      * Destructor.

    63      */

    64     virtual ~CNATFWConnectivityApi();

    65 

    66     /**

    67      * Registers an observer for the specified events. Same observer can be

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

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

    70      * eventdata.

    71      *

    72      * Refer to MNATFWConnectivityObserver API for event definitions.

    73      *

    74      * @since   S60 v3.2

    75      * @param   aObserver       Observer for NAT Connectivity API events

    76      * @param   aEvents         Events for which to register

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

    78      *  the events

    79      */

    80     void RegisterObserverForEventsL( MNATFWConnectivityObserver& aObserver,

    81         TUint16 aEvents );

    82 

    83     /**

    84      * Unregisters an observer for the specified events.

    85      *

    86      * Refer to MNATFWConnectivityObserver API for event definitions.

    87      *

    88      * @since   S60 v3.2

    89      * @param   aObserver       Observer for NAT Connectivity API events

    90      * @param   aEvents         Events for which to unregister

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

    92      *          any more.

    93      */

    94     void UnregisterObserverForEvents( MNATFWConnectivityObserver& aObserver,

    95         TUint16 aEvents );

    96 

    97     /**

    98      * Creates a new NAT-session. On return the client receives identifier for

    99      * the session.

   100      *

   101      * The session is ready to be used when the client receives

   102      * MNATFWConnectivityObserver::Notify callback with event code

   103      * ESessionCreated.

   104      *

   105      * @since   S60 v3.2

   106      * @param   aIapId          The IAP used for a connection

   107      * @param   aDomain         Used domain for settings query

   108      * @return  The ID for the created session

   109      */

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

   111 

   112     /**

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

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

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

   116      *

   117      * Given NAT protocol plugins are tried to load in order until working

   118      * one is found.

   119      *

   120      * @since   S60 v3.2

   121      * @pre     NAT session is created

   122      * @param   aSessionId      The ID identifying session

   123      * @param   aPlugins        Array containing identifiers for available

   124      *  NAT-protocol plugins in preferred order. E.g. "exampleprovider.stun".

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

   126      *  loaded plugin.

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

   128      * @leave   KErrNotFound NAT-plugin was not found

   129      */

   130     IMPORT_C void LoadPluginL( TUint aSessionId, const CDesC8Array& aPlugins,

   131         TInt& aLoadedPluginInd );

   132 

   133     /**

   134      * Creates a new NAT-stream to the session. On return the client receives

   135      * identifier for the stream.

   136      *

   137      * @since   S60 v3.2

   138      * @param   aSessionId      The ID identifying session

   139      * @param   aProtocol       KProtocolInetUdp / KProtocolInetTcp

   140      * @param   aQoS            The desired quality of service

   141      * @return  The ID for the created stream

   142      */

   143     IMPORT_C TUint CreateStreamL( TUint aSessionId,

   144         TUint aProtocol, TInt aQoS );

   145 

   146     /**

   147      * Creates a wrapper for the specified stream.

   148      *

   149      * @since   S60 v3.2

   150      * @param   aSessionId      The ID identifying session

   151      * @param   aStreamId       The ID identifying stream

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

   153      */

   154     IMPORT_C MNATFWSocketMediaConnWrapper& CreateWrapperL(

   155         TUint aSessionId, TUint aStreamId );

   156 

   157     /**

   158      * Resolves public transport address to be used in the communication

   159      * between peers. 

   160      * 

   161      * MNATFWConnectivityObserver::NewLocalCandidateFound is called when

   162      * the candidate has been resolved.

   163      * 

   164      * MNATFWConnectivityObserver::Notify is called with event code 

   165      * EFetchingCompleted when resolving process has completed.

   166      * 

   167      * Address of given family is tried to resolve.

   168      * 

   169      * @since   S60 v3.2

   170      * @param   aSessionId      The ID identifying session

   171      * @param   aStreamId       The ID identifying stream

   172      * @param   aAddrFamily     KAFUnspec / KAfInet / KAfInet6

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

   174      * operation.

   175      */

   176     IMPORT_C void FetchCandidateL( TUint aSessionId, TUint aStreamId,

   177         TUint aAddrFamily );

   178 

   179     /**

   180      * ICE spesific function.

   181      * Fetches transport address candidates for the communication between

   182      * peers. Client is responsible for providing mapping between components

   183      * of media stream through collection identifier.

   184      *

   185      * MNATFWConnectivityObserver::NewLocalCandidateFound is called whenever

   186      * a new candidate has been found.

   187      *

   188      * MNATFWConnectivityObserver::Notify is called with event code

   189      * EFetchingCompleted when all available candidates are gathered.

   190      * 

   191      * Only candidates of specified family are tried to gather. With KAFUnspec

   192      * candidates of all address families are tried to resolve.

   193      *

   194      * @since   S60 v3.2

   195      * @param   aSessionId      The ID identifying session

   196      * @param   aStreamId       The ID identifying stream

   197      * @param   aCollectionId   The stream collection identifier

   198      * @param   aComponentId    The media component identifier

   199      * @param   aAddrFamily     KAFUnspec / KAfInet / KAfInet6

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

   201      * operation.

   202      */

   203     IMPORT_C void FetchCandidatesL(

   204         TUint aSessionId, TUint aStreamId,

   205         TUint aCollectionId, TUint aComponentId, TUint aAddrFamily );

   206     

   207     /**

   208      * ICE specific function.

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

   210      * will be silently changed.

   211      *

   212      * @since   S60 v3.2

   213      * @param   aSessionId      The ID identifying session

   214      * @param   aRole           The role to take

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

   216      * operation.

   217      */

   218     IMPORT_C void SetRoleL( TUint aSessionId, TNATFWIceRole aRole );

   219 

   220     /**

   221      * ICE specific function. Sets username fragment and corresponding

   222      * password for message signing and authentication with the specified

   223      * candidate.

   224      *

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

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

   227      *

   228      * @since   S60 v3.2

   229      * @param   aCandidate      The candidate

   230      * @param   aCredentials    The credentials

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

   232      * operation.

   233      */

   234     IMPORT_C void SetCredentialsL(

   235         CNATFWCandidate& aCandidate,

   236         const CNATFWCredentials& aCredentials );

   237 

   238     /**

   239      * ICE specific function.

   240      * Performs connectivity checks between the local candidates and the

   241      * remote candidates.

   242      *

   243      * MNATFWConnectivityObserver::NewCandidatePairFound

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

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

   246      *

   247      * MNATFWConnectivityObserver::Notify is called with event code

   248      * EConnChecksCompleted for each NATFW-stream when ICE process has

   249      * completed for that stream.

   250      *

   251      * Function can be used for starting initial connectivity tests and

   252      * ICE restarts for the stream(s). Restart requires updating of

   253      * role and credentials before calling this function.

   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     Role and credentials are set

   260      * @param   aSessionId      The ID identifying session

   261      * @param   aRemoteCands    The remote candidate array

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

   263      * operation.

   264      */

   265     IMPORT_C void PerformConnectivityChecksL( TUint aSessionId,

   266         RPointerArray<CNATFWCandidate>& aRemoteCands );

   267 

   268     /**

   269      * ICE specific function.

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

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

   272      * update for that is silently ignored.

   273      *

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

   275      * re-starting connectivity checks with PerformCandidateChecksL.

   276      *

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

   278      * Removing of streams is handled with CloseStreamL.

   279      *

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

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

   282      *

   283      * @since   S60 v3.2

   284      * @pre     ICE processing is started with PerformConnectivityChecksL

   285      * @param   aSessionId          The ID identifying session

   286      * @param   aPeerSelectedPairs  Peer selected candidate pairs

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

   288      * operation.

   289      * @post    ICE processing is continued with new parameters

   290      */

   291     IMPORT_C void UpdateIceProcessingL( TUint aSessionId,

   292         RPointerArray<CNATFWCandidatePair>& aPeerSelectedPairs );

   293 

   294     /**

   295      * ICE specific function.

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

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

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

   299      * connectivity tests from this point onwards.

   300      *

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

   302      * re-starting connectivity checks with PerformCandidateChecksL.

   303      *

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

   305      * Removing of streams is handled with CloseStreamL.

   306      *

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

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

   309      *

   310      * @since   S60 v3.2

   311      * @pre     ICE processing is started with PerformConnectivityChecksL

   312      * @param   aSessionId          The ID identifying session

   313      * @param   aRemoteCands        All remote candidates known currently

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

   315      * operation.

   316      * @post    ICE processing is continued with new parameters

   317      */

   318     IMPORT_C void UpdateIceProcessingL( TUint aSessionId,

   319         RPointerArray<CNATFWCandidate>& aRemoteCands );

   320 

   321     /**

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

   323      * 

   324      * Only those candidates given with MNATFWConnectivityObserver callbacks

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

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

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

   328      * 

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

   330      * resources can be freed.

   331      * 

   332      * MNATFWConnectivityObserver::Notify is called with event code

   333      * EReceivingActivated/EReceivingDeactivated when state change has 

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

   335      * engine.

   336      * 

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

   338      * is known.

   339      * 

   340      * @since   S60 v3.2

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

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

   343      * @param   aState          The receiving state

   344      */

   345     IMPORT_C void SetReceivingStateL( const CNATFWCandidate& aLocalCandidate,

   346         TNATFWStreamingState aState );

   347     

   348     /**

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

   350      * 

   351      * Only those candidates given with MNATFWConnectivityObserver callbacks

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

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

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

   355      * 

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

   357      * resources can be freed.

   358      * 

   359      * MNATFWConnectivityObserver::Notify is called with event code

   360      * ESendingActivated/ESendingDeactivated when state change has 

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

   362      * to the specified remote address.

   363      * 

   364      * @since   S60 v3.2

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

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

   367      * @param   aState          The sending state

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

   369      */

   370     IMPORT_C void SetSendingStateL( const CNATFWCandidate& aLocalCandidate,

   371         TNATFWStreamingState aState, const TInetAddr& aDestAddr );

   372     

   373     /**

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

   375      * 

   376      * MNATFWConnectivityObserver::Notify is called with event code

   377      * ESendingActivated/ESendingDeactivated when state change has 

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

   379      * to the specified FQDN address and port.

   380      * 

   381      * @since   S60 v3.2

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

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

   384      * @param   aState          The streaming state

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

   386      * @param   aPort           The destination port for the media

   387      */

   388     IMPORT_C void SetSendingStateL( const CNATFWCandidate& aLocalCandidate,

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

   390 

   391     /**

   392      * Closes the specified stream.

   393      *

   394      * @since   S60 v3.2

   395      * @pre     Streaming is disabled with SetReceivingStateL/SetSendingStateL

   396      * @param   aSessionId      The ID identifying session

   397      * @param   aStreamId       The ID identifying stream

   398      */

   399     IMPORT_C void CloseStreamL( TUint aSessionId, TUint aStreamId );

   400 

   401     /**

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

   403      * closed too.

   404      *

   405      * @since   S60 v3.2

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

   407      *          the session

   408      * @param   aSessionId      The ID identifying session

   409      */

   410     IMPORT_C void CloseSessionL( TUint aSessionId );

   411 

   412 private:

   413 

   414     CNATFWConnectivityApi();

   415 

   416     void ConstructL();

   417 

   418 private: // data

   419 

   420     /**

   421      * Pointer to the implementor of the NAT Connectivity FW API

   422      * Own.

   423      */

   424     CNATFWClient* iClient;

   425 

   426     };

   427 

   428 #endif // NATCONNECTIVITYFW_H