1 /*

     2 * Copyright (c) 2005-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:    

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef C_CSTUNBINDINGIMPLEMENTATION_H

    22 #define C_CSTUNBINDINGIMPLEMENTATION_H

    23 

    24 // INCLUDES

    25 #include <e32base.h>

    26 #include <es_sock.h>

    27 #include <in_sock.h>

    28 #include "mstuntransactionobserver.h"

    29 #include "cstuntimeruser.h"

    30 #include "natfwbindingimplementationbase.h"

    31 #include "stunturnclientlogs.h"

    32 

    33 // FORWARD DECLARATIONS

    34 class MSTUNBindingObserver;

    35 class MNcmConnectionMultiplexer;

    36 

    37 // CLASS DECLARATION

    38 /**

    39 * Hides the implementation of STUN binding for the user of STUN client.

    40 * @lib  natfwstunclient.dll

    41 */

    42 class CSTUNBindingImplementation : public CBindingImplementation

    43     {

    44     friend class ut_cstunbindingimplementation;

    45     

    46     public:  // Constructors and destructor

    47 

    48         /**

    49         * Creates a new instance of CSTUNBindingImplementation.

    50         * Associates the local socket with the binding.

    51         * The public IP address is available when

    52         * MSTUNClientObserver::STUNBindingEventOccuredL gets called.

    53         *

    54         * @since    s60 3.2

    55         * @pre      aClient.IsInitialized()

    56         * @param    aBinding Associated binding interface

    57         * @param    aClient An initialised STUN client

    58         * @param    aSocket An opened socket that has the local port set.

    59         * @param    aStreamId stream id

    60         * @param    aSubstreamId substream id

    61         * @return a new instance, the ownership is transferred.

    62         */

    63         static CSTUNBindingImplementation* NewL( CBinding& aBinding,

    64                                                  MSTUNBindingObserver& aClient,

    65                                                  RSocket& aSocket );

    66         

    67         /**

    68          * Creates a new instance of CSTUNBindingImplementation.

    69          * Associates the local socket with the binding.

    70          * The public IP address is available when

    71          * MSTUNClientObserver::STUNBindingEventOccuredL gets called.

    72          *

    73          * @since    s60 3.2

    74          * @pre      aClient.IsInitialized()

    75          * @param    aBinding Associated binding interface

    76          * @param    aClient An initialised STUN client

    77          * @param    aStreamId stream id

    78          * @param    aSubstreamId substream id

    79          * @return a new instance, the ownership is transferred.

    80          */

    81         static CSTUNBindingImplementation* NewL( CBinding& aBinding,

    82                                          MSTUNBindingObserver& aClient,

    83                                          TUint aStreamId,

    84                                          TUint aSubstreamId,

    85                                          MNcmConnectionMultiplexer* aMux );

    86         /**

    87         * Destructor.

    88         */

    89         ~CSTUNBindingImplementation();

    90 

    91     public: // From CSTUNTimerUser

    92 

    93         void TimerExpiredL();

    94 

    95         void LeaveFromTimerExpired( TInt aError );

    96 

    97     public: // From MSTUNTransactionObserver

    98 

    99         void PublicAddressObtainedL( const TInetAddr& aAddress );

   100 

   101         void PublicAddressObtainedL( const TInetAddr& aReflexiveAddr,

   102                                      const TInetAddr& aRelayAddr );

   103 

   104         void TransactionError( TInt aError,

   105                                CNATFWUNSAFUnknownAttributesAttribute* aUnknownAttr );

   106 

   107         void TransactionEventOccurredL( TSTUNCallbackInfo::TFunction aEvent );

   108         

   109     public: // New functions

   110 

   111         /**

   112          * Refreshes the binding causing a new Binding Request to be sent

   113          * to the STUN server. The public IP address is available when 

   114          * MSTUNClientObserver gets called.

   115          *

   116          * @since    s60 3.2

   117          * @return   void

   118          */

   119         void SendRequestL();

   120         

   121         /**

   122          * Overloaded version of SendRequestL().

   123          *

   124          * @since   S60 v3.2

   125          * @param   aDestAddr       Destination where to send request

   126                                     (KAFUnspec=default address)

   127          * @param   aAddFingerprint Whether to include fingerprint attribute

   128                                     to request

   129          * @param   aRtoValue       Retransmission timeout

   130                                     (=0 if default to be used)

   131          * @return  void

   132          */

   133         void SendRequestL( const TInetAddr& aDestAddr,

   134                            TBool aAddFingerprint,

   135                            TUint aRtoValue );

   136                 

   137         /**

   138          * Cancels a previously issued call to SendRequestL.

   139          *

   140          * @since    s60 3.2

   141          * @return   void

   142          */

   143         void CancelRequest();

   144 

   145         /**

   146          * Gets the socket used for obtaining the public address.

   147          *

   148          * @since    s60 3.2

   149          * @return socket

   150          */

   151         const RSocket& Socket() const;    

   152     

   153         /**

   154          * Checks whether the public address has a value set

   155          *

   156          * @since    s60 3.2

   157          * @return ETrue if the public address has been obtained, 

   158          *         otherwise EFalse. 

   159          */

   160         TBool AddressResolved() const;    

   161     

   162         /**

   163          * Gets the public address for this binding as seen in public network.

   164          *

   165          * @since    s60 3.2

   166          * @return   public address

   167          */

   168         const TInetAddr& PublicAddr() const;

   169         

   170         /**

   171          * Returns alternate server transport address.

   172          *

   173          * @since   s60 3.2

   174          * @return alternate server address

   175          */

   176         const TInetAddr& AlternateServerAddr() const;

   177         

   178         /**

   179          * Returns realm value from error response.

   180          *

   181          * @since   s60 3.2

   182          * @return realm from error response         

   183          */

   184         const HBufC8* RealmFromResponse() const;        

   185         

   186         /**

   187          * The client should call this function when it has received data

   188          * from the socket shared with this binding and 

   189          * the client cannot itself handle the data.

   190          *

   191          * @since    s60 3.2

   192          * @param    aData data received

   193          * @param    aConsumed on return ETrue if the data was accepted,

   194          *           otherwise EFalse.

   195          * @param    aRemoteAddr KAFUnspec

   196          * @return   NULL.

   197          */

   198         HBufC8* HandleDataL( 

   199             const TDesC8& aData, TBool& aConsumed, TInetAddr& aRemoteAddr );

   200 

   201 

   202         /**

   203          * Returns the associated CSTUNClient instance.

   204          *

   205          * @since    s60 3.2

   206          * @return CSTUNClient, or NULL if the CSTUNClient has been deleted        

   207          */

   208         const CSTUNClient* STUNClient() const;

   209 

   210         /**

   211          * Get a STUN server address from STUN client

   212          *

   213          * @since    s60 3.2

   214          * @return   void

   215          */

   216         void GetServerAddressL();

   217         

   218         /**

   219          * Get a fresh a shared secret.

   220          *

   221          * @since    s60 3.2

   222          * @return   void  

   223          */

   224         void GetSharedSecretL();

   225 

   226         /**

   227          * Clears the pointer to CSTUNClient.

   228          *

   229          * @since    s60 3.2

   230          * @return   void

   231          * @post     iClient == NULL        

   232          */

   233         void DetachClient();

   234 

   235         /**

   236          * Store the obtained public address and inform application.

   237          *

   238          * @since    s60 3.2

   239          * @param    aPublicAddress Public address

   240          * @return   void

   241          */        

   242         void StoreAddressL( const TInetAddr& aPublicAddress );

   243 

   244         /**

   245          * Change the object's state.

   246          *

   247          * @since    s60 3.2

   248          * @param    aNewState State to enter.

   249          * @return   void

   250          */

   251         void ChangeState( CSTUNBindingState& aNewState );

   252         

   253         /**

   254          * Binding encountered an error and enters terminated state. The function

   255          * MSTUNClientObserver::BindingErrorL is used to inform application.

   256          *

   257          * @since    s60 3.2

   258          * @pre      aError != KErrNone

   259          * @param    aError Error code

   260          * @return   void

   261          */

   262         void Terminate( TInt aError );        

   263         

   264         /**

   265          * Checks if this binding is waiting for shared secret.

   266          *

   267          * @since    s60 3.2

   268          * @return ETrue BInding is waiting shared secret, EFalse otherwise

   269          */

   270         TBool IsWaitingSharedSecret() const;

   271 

   272         /**

   273          * STUN client uses this function to give the username and password, that

   274          * the binding requested earlier with function

   275          * MSTUNBindingObserver::ObtainSharedSecretL.

   276          *

   277          * @since    s60 3.2

   278          * @pre      aUsername and aPassword must either both have a descriptor that

   279          *           is not empty, or then both must have an empty descritor.

   280          * @param    aUsername Username or an empty descriptor if the shared secret

   281          *                    is not used.

   282          * @param    aPassword Password or an empty descriptor if the shared secret

   283          *                    is not used.

   284          * @return   void

   285          */

   286         void SharedSecretObtainedL( const TDesC8& aUsername,

   287                                     const TDesC8& aPassword );

   288 

   289         /**

   290          * Creates or updates a Binding Request message, using the given username

   291          * and password.

   292          *

   293          * @since    s60 3.2

   294          * @param    aUsername Username

   295          * @param    aPassword Password

   296          * @return   void

   297          */

   298         void CreateBindingRequestL( const TDesC8& aUsername,

   299                                     const TDesC8& aPassword );

   300 

   301         /**

   302          * Creates a transaction for sending Binding Request message

   303          *

   304          * @since    s60 3.2

   305          * @pre      iRequest != NULL

   306          * @return   void   

   307          */                          

   308         void SendBindingRequestL();

   309         

   310         /**

   311          * Take actions based on the reason why transaction failed. For certain

   312          * errors, it is possible to send the Binding Request again.

   313          * 

   314          * @since    s60 3.2

   315          * @pre      aError != KErrNone

   316          * @param    aError Error reason

   317          * @return   ETrue Request can be retried

   318          *           EFalse Binding enters Terminated-state

   319          */

   320         TBool HandleTransactionError( TInt aError );

   321 

   322         /**

   323          * Forward the ICMP error to transaction for processing.

   324          *

   325          * @since    s60 3.2

   326          * @param    aAddress Address where the ICMP error occurred

   327          * @return   void      

   328          */

   329         void IcmpError( const TInetAddr& aAddress );

   330 

   331         /**

   332          * Wait before retring to send a Binding Request

   333          *

   334          * @since    s60 3.2

   335          * @return   void      

   336          */

   337         void WaitBeforeRetrying();

   338         

   339         /**

   340          * ICE specific cancel for stopping ongoing message retranstmition.

   341          * Response is waited as long as sending timer expires. After that

   342          * MSTUNClientObserver::STUNBindingErrorOccurred method will be called.

   343          *

   344          * @since   s60 3.2

   345          * @return  void

   346          */

   347         void CancelRetransmission();

   348        

   349         /**

   350          * Method for sending binding indication. Indications are not

   351          * are not retransmitted and responses are not expected.

   352          *

   353          * @since   s60 3.2

   354          * @param   aRemoteAddr     address to send to (remote agent)

   355          * @param   aData           data to sent in indication

   356          * @param   aAddFingerprint add fingerprint attribute if true

   357          * @return  void

   358          */

   359         void SendIndicationL( const TInetAddr& aRemoteAddr,

   360             const TDesC8& aData, TBool aAddFingerprint );

   361             

   362         

   363         // From CBindingImplementationBase

   364 

   365         void SetICESpecificAttributes( const TICEAttributes& aAttributes );

   366         

   367         TUint StreamId() const;

   368         

   369         TUint ConnectionId() const;

   370 

   371         const CBinding& Binding();

   372 

   373     private: // Constructors, for internal use

   374 

   375         CSTUNBindingImplementation( CBinding& aBinding,        

   376                                     MSTUNBindingObserver& aClient,

   377                                     RSocket& aSocket );

   378         

   379         CSTUNBindingImplementation( CBinding& aBinding,

   380                                     MSTUNBindingObserver& aStunClient, 

   381                                     TUint aStreamId,

   382                                     TUint aSubstreamId,

   383                                     MNcmConnectionMultiplexer* aMux );

   384 

   385         void ConstructL();

   386         CSTUNBindingImplementation();

   387 

   388     private: // New functions, for internal use

   389 

   390         /**

   391          * Release the memory of the Binding Request related data. This data is

   392          * only needed for sending a Binding Request and receiving a response.

   393          *

   394          * @since    s60 3.2

   395          * @return   void

   396          */

   397         void FreeRequestData();

   398 

   399         /**

   400          * Return STUN client handle.

   401          *

   402          * @since   s60 3.2

   403          * @pre iClient != NULL

   404          * @return STUN client

   405          * @leave KErrNotFound If the STUN client has been deleted

   406          */

   407         MSTUNBindingObserver& ClientL() const;

   408 

   409         /**

   410          * Return the current username, or an empty descriptor if username

   411          * does not exist.

   412          *

   413          * @since   s60 3.2

   414          * @return  Username

   415          */

   416         const TDesC8& Username() const;

   417 

   418         /**

   419          * Checks if the STUN server has requested client to use a shared secret.

   420          *

   421          * @since   s60 3.2

   422          * @return ETrue if STUN server requires the use of a shared secret

   423          *          EFalse otherwise

   424          */

   425         TBool IsSharedSecretRequired() const;

   426 

   427         /**

   428          * Decodes a byte stream and return the decoded UNSAF message.

   429          *

   430          * @since   s60 3.2

   431          * @param   aData Byte stream to decode

   432          * @return  Decoded message, ownership is transferred.

   433          *          NULL if the stream didn't contain an UNSAF message.

   434          */

   435         CNATFWUNSAFMessage* DecodeMessageL( const TDesC8& aData ) const;

   436         

   437         /**

   438          * Validate message data.

   439          *

   440          * @since   s60 3.2

   441          * @param   aMsg pointer to unsaf message

   442          * @return  ETrue if valid message type, else EFalse

   443          */

   444         TBool ValidateMsgType( CNATFWUNSAFMessage* aMsg ) const;

   445 

   446     private: // Data

   447         

   448         TInetAddr iDestAddr;

   449         

   450     private: // For testing purposes

   451 

   452 #ifdef TEST_EUNIT

   453         friend class CSTUNClientTest;

   454         friend class CSTUNClientImplementationTest;

   455         friend class CSTUNBindingTest;

   456         friend class CSTUNBindingImplementationTest;

   457 #endif

   458     };

   459 

   460 #endif // CSTUNBINDINGIMPLEMENTATION_H

   461 

   462 // End of File