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:  Session class description.

    15 *

    16 */

    17 

    18 #ifndef NSPSESSION_H

    19 #define NSPSESSION_H

    20 

    21 #include <e32base.h>

    22 #include <in_sock.h>

    23 #include "nspplugin.h"

    24 #include "nsppluginreturndef.h"

    25 #include "natfwconnectivityapidefs.h"

    26 #include "mnatfwconnectivityobserver.h"

    27 #include "nspsessiondata.h"

    28 #include "nspdefs.h"

    29 #include "nsputdefinitions.h"

    30 

    31 class CDesC8Array;

    32 class CSdpDocument;

    33 class CNATFWCandidate;

    34 class CNATFWCandidatePair;

    35 class MNSPSessionObserver;

    36 class MNSPControllerIF;

    37 class CNSPContentParser;

    38 class CNSPMediaStreamContainer;

    39 class CNSPStateMachine;

    40 class TNSPActionSet;

    41 class TEventReturnStatus;

    42 

    43 /**

    44  *  Session object that handles client requests.

    45  *

    46  *  Session encloses all Sdp data in separate object, which is then 

    47  *  used by state machine object. After state machine completes 

    48  *  processing, session notifies client via observer callbacks.

    49  *

    50  *  @lib natfwsdpprovider.dll

    51  *  @since S60 3.2

    52  */

    53 class CNSPSession : public CBase

    54     {

    55 public: // Enumerations

    56 

    57     /**

    58      * The role of session, in signalling.

    59      */

    60     enum TSdpRole

    61         {

    62         EUndefined,

    63         EOfferer,

    64         EAnswerer

    65         };

    66 

    67 

    68 public: // Constructors and destructor

    69     

    70     /**

    71      * A two-phase constructor.

    72      */

    73     static CNSPSession* NewL( MNSPControllerIF& aController,

    74             MNSPSessionObserver& aSessionObserver, TUint32 aIapId,

    75             const TDesC8& aDomain, TUint aProtocol );

    76     

    77     /**

    78      * A two-phase constructor.

    79      */

    80     static CNSPSession* NewLC( MNSPControllerIF& aController,

    81             MNSPSessionObserver& aSessionObserver, TUint32 aIapId,

    82             const TDesC8& aDomain, TUint aProtocol );

    83     

    84     /**

    85      * Destructor.

    86      */

    87     virtual ~CNSPSession();

    88     

    89 

    90 private: // Constructors and destructor

    91 

    92     CNSPSession( MNSPControllerIF& aController, MNSPSessionObserver& aSessionObserver );

    93     

    94     void ConstructL( TUint32 aIapId, const TDesC8& aDomain, TUint aProtocol );

    95 

    96 

    97 public: // New functions

    98 

    99     /**

   100      * This method is used to create NAT FW modified Sdp content, 

   101      * based on initially given Sdp offer.

   102      * 

   103      * @since       S60 3.2

   104      * @param       aOffer              Sdp document object, initial Offer.

   105      */

   106     TNatReturnStatus CreateOfferL( CSdpDocument*& aOffer );

   107     

   108     /**

   109      * This method is used to create NAT FW modified Sdp content, 

   110      * Both Offer and Answer, according to received Offer.

   111      * 

   112      * @since       S60 3.2

   113      * @param       aOffer              Sdp document object, initially 

   114      *                                  received Offer.

   115      * @param       aAnswer             Sdp document object, initial Answer.

   116      *                                  ( non NAT FW modified )

   117      */

   118     TNatReturnStatus ResolveL( CSdpDocument*& aOffer, CSdpDocument*& aAnswer );

   119     

   120     /**

   121      * This method is used to interpret NAT FW modified Sdp content, 

   122      * decode Answer based on initially modified Offer.

   123      * 

   124      * @since       S60 3.2

   125      * @param       aAnswer             Sdp document object, Answer to 

   126      *                                  initial offer.

   127      */

   128     TNatReturnStatus DecodeAnswerL( CSdpDocument*& aAnswer );

   129     

   130     /**

   131      * Offer can be updated while ResolveL is still ongoing, i.e.

   132      * OfferReady callback is not yet received.

   133      * 

   134      * @since       S60 3.2

   135      * @param       aOffer              Sdp offer document

   136      */

   137     void UpdateL( CSdpDocument*& aOffer );

   138     

   139     /**

   140      * Session closing must be done in asynchronous manner.

   141      *

   142      * @since       S60 3.2

   143      */

   144     TNatReturnStatus CloseSessionL();

   145     

   146     /**

   147      * This method is used to mediate NAT FW events to corresponding 

   148      * handler object.

   149      * 

   150      * @since       S60 3.2

   151      * @param       aStreamId           The ID identifying stream(from NAT FW)

   152      * @param       aEvent              The event.

   153      * @param       aError              The completion code of the operation

   154      * @return      Returns error code if failure in event handling.

   155      */

   156     TEventReturnStatus EventOccured( TUint aStreamId,

   157     		MNATFWConnectivityObserver::TNATFWConnectivityEvent aEvent,

   158     		TInt aError, TAny* aData );

   159     

   160     /**

   161      * Callback method that is used to inform about updated Sdp Offer, asynchronously.

   162      * Ownership of the argument is transferred.

   163      * 

   164      * @since       S60 3.2

   165      * @param       aDocument           Sdp document object, updated Offer.

   166      */

   167     void UpdateSdpAsyncL( CSdpDocument* aDocument );

   168     

   169     /**

   170      * This method is used to get unique session identifier.

   171      *

   172      * @since       S60 3.2

   173      * @return      The ID identifying stream.

   174      */

   175     TUint SessionId() const;

   176     

   177     /**

   178      * This method is used to access peer specific session data.

   179      *

   180      * @since       S60 3.2

   181      * @return      Reference to session data object.

   182      */

   183     CNSPSessionData& Data();

   184     

   185     /**

   186      * This method is used to access host specific media stream container.

   187      *

   188      * @since       S60 3.2

   189      * @return      Reference to stream container object.

   190      */

   191     CNSPMediaStreamContainer& Container();

   192     

   193     /**

   194      * This method is used to access array containing protocol strings.

   195      *

   196      * @since       S60 3.2

   197      * @return      Reference to descriptor array.

   198      */

   199     CDesC8Array& Plugins();

   200     

   201     /**

   202      * Removes all strings from the given array which contain postfix ".ice".

   203      * 

   204      * @since       S60 3.2

   205      * @param       aDesArray           Array of descriptors

   206      */    

   207     void RemoveIce( CDesC8Array& aDesArray ) const;

   208     

   209     /**

   210      * Checks if given string contains postfix ".ice".

   211      * 

   212      * @since       S60 3.2

   213      * @param       aProtocol           Protocol string

   214      */

   215     TBool IsIce( const TDesC8& aProtocol ) const;

   216 

   217     /**

   218      * This method is used to access content parsing methods.

   219      *

   220      * @since       S60 3.2

   221      * @return      Reference to content parser object.

   222      */

   223     const CNSPContentParser& Parser() const;

   224     

   225     /**

   226      * This method is used to retrieve O/A - role from the session.

   227      *

   228      * @since       S60 3.2

   229      * @return      Current role of the session

   230      */

   231     CNSPSession::TSdpRole& Role();

   232     

   233     /**

   234      * This method is used to get session specific identifier.

   235      *

   236      * @since       S60 3.2

   237      * @return      Session observer reference

   238      */

   239     MNSPSessionObserver& SessionObserver() const;

   240     

   241     /**

   242      * This method is used to get state machine actions.

   243      *

   244      * @since       S60 3.2

   245      * @return      Action set object, automatic object from stack.

   246      */

   247     TNSPActionSet Actions();

   248     

   249     /**

   250      * This method is used to set session specific parameters.

   251      *

   252      * @since       S60 3.2

   253      * @param       aParamKey           Enumeration key identifying parameter.

   254      * @param       aParamValue         Value of the parameter.

   255      * @return      status code

   256      */

   257     TInt SetSessionParam( CNSPPlugin::TNSPSessionParamKey aParamKey,

   258             TUint aParamValue );

   259     

   260     /**

   261      * This method is used to set gession specific parameters.

   262      *

   263      * @since       S60 3.2

   264      * @param       aParamKey           Enumeration key identifying parameter.

   265      * @return      parameter value, or error in failure situations.

   266      */

   267     TInt GetSessionParam( CNSPPlugin::TNSPSessionParamKey aParamKey );

   268     

   269     /**

   270      * This method is used to set NAT FW specific flag for session, 

   271      * specifying which NAT protocol should be used as default, 

   272      * STUN or ICE/TURN.

   273      *

   274      * @since       S60 3.2

   275      * @param       aUseIce             ETrue if ICE is in use.

   276      */

   277     void SetUseIce( TBool aUseIce );

   278 

   279 

   280 

   281 private: // New functions

   282 

   283     void Proceed( TInt aRequest, TNatReturnStatus& aStatus );

   284 

   285 

   286 private: // data

   287 

   288     /**

   289      * This reference is needed for informing controller that session was

   290      * deleted by the user, and hence NAT FW events are no longer acceptable.

   291      * Not own.

   292      */

   293     MNSPControllerIF& iController;

   294     

   295     /**

   296      * Session observer reference.

   297      * Not own.

   298      */

   299     MNSPSessionObserver& iSessionObserver;

   300 

   301     /**

   302      * Session identifier, received from NAT FW.

   303      */

   304     TUint iSessionId;

   305     

   306     /**

   307      * Flag indicating the role of the session, Offerer / Answerer.

   308      */

   309     TSdpRole iRole;

   310     

   311     /**

   312      * Session data container.

   313      * Own.

   314      */

   315     CNSPSessionData* iSessionData;

   316     

   317     /**

   318      * Session media stream container.

   319      * Own.

   320      */

   321     CNSPMediaStreamContainer* iStreamContainer;

   322     

   323     /**

   324      * Session state machine, i.e. actions.

   325      * Own.

   326      */

   327     CNSPStateMachine* iStateMachine;

   328     

   329     /**

   330      * Protocols array, strings containing the name of used protocol.

   331      * Own.

   332      */

   333     CDesC8Array* iProtocolsArray;

   334     

   335     /**

   336      * Definitions for unit testing.

   337      */

   338     NSP_UT_DEFINITIONS

   339 

   340     };

   341 

   342 #define OFFERER( role ) ( CNSPSession::EOfferer == role )

   343 #define ANSWERER( role ) ( CNSPSession::EAnswerer == role )

   344 

   345 #endif // NSPSESSION_H

   346 

   347 // end of file