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 STUN binding services.

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 

    22 #ifndef CSTUNBINDING_H

    23 #define CSTUNBINDING_H

    24 

    25 #include <e32base.h>

    26 #include "natfwbindingbase.h"

    27 

    28 /**

    29  * A class for sending STUN Binding Requests and 

    30  * obtaining the public IP address as seen by the STUN server. 

    31  * @lib natfwstunclient.lib

    32  */

    33 class CSTUNBinding : public CBinding

    34     {

    35     friend class CSTUNBindingTest;

    36     friend class ut_cstunclientimplementation;

    37 

    38 public:

    39 

    40     /**

    41      * Two-phased constructor.

    42      * Associates the local socket with the binding.

    43      *

    44      * @pre     aSTUNClient.IsInitialized()

    45      * @pre     aSocket must have been opened

    46      * @param   aSTUNClient an initialised STUN client

    47      * @param   aSocket an opened socket that has the local port set.

    48      */

    49     IMPORT_C static CSTUNBinding* NewL( CSTUNClient& aSTUNClient,

    50         RSocket& aSocket );

    51 

    52     /**

    53      * Two-phased constructor.

    54      * Overloaded version.

    55      *

    56      * @since   s60 v3.2

    57      * @pre     aSTUNClient.IsInitialized()

    58      * @param   aSTUNClient an initialised STUN client

    59      * @param   aStreamId Stream identifier

    60      * @param   aConnectionId Connection identifier

    61      */

    62     IMPORT_C static CSTUNBinding* NewL( CSTUNClient& aSTUNClient, 

    63         TUint aStreamId, TUint aConnectionId );

    64         

    65     /**

    66      * Two-phased constructor.

    67      *

    68      * @pre     aSTUNClient.IsInitialized()

    69      * @pre     aSocket must have been opened

    70      * @param   aSTUNClient an initialised STUN client

    71      * @param   aSocket an opened socket that has the local port set.

    72      */

    73     IMPORT_C static CSTUNBinding* NewLC( CSTUNClient& aSTUNClient, 

    74         RSocket& aSocket );          

    75 

    76     /**

    77      * Two-phased constructor.

    78      *

    79      * @since   s60 v3.2

    80      * @pre     aSTUNClient.IsInitialized()

    81      * @param   aSTUNClient an initialised STUN client

    82      * @param   aStreamId Stream identifier

    83      * @param   aConnectionId Connection identifier

    84      */

    85     IMPORT_C static CSTUNBinding* NewLC( CSTUNClient& aSTUNClient, 

    86         TUint aStreamId, TUint aConnectionId );          

    87 

    88     /**

    89      * Destructor.

    90      */

    91     IMPORT_C ~CSTUNBinding();

    92 

    93     /**

    94      * Executes STUN binding request.

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

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

    97      * MSTUNClientObserver gets called.

    98      * If application provided credentials with CSTUNClient::SetCredentialsL

    99      * or if parameter aObtainSharedSecret was ETrue when CSTUNClient was

   100      * created, USERNAME and MESSAGE-INTEGRITY attributes are put into the

   101      * Binding Request.

   102      *

   103      * @return  void

   104      */

   105     IMPORT_C void SendRequestL();

   106 

   107     /**

   108      * Overloaded version of SendRequestL().

   109      *

   110      * @since   s60 v3.2

   111      * @param   aDestAddr       Destination where to send request 

   112      *                          (KAFUnspec=default address)

   113      * @param   aAddFingerprint Whether to include fingerprint attribute

   114      *                          to request

   115      * @param   aRtoValue       Retransmission timeout

   116      *                          (0 = default value to be used)

   117      * @return  void

   118      */

   119     IMPORT_C void SendRequestL( const TInetAddr& aDestAddr,

   120         TBool aAddFingerprint, TUint aRtoValue );

   121     

   122     /**

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

   124      *

   125      * @return  socket

   126      */

   127     IMPORT_C const RSocket& Socket() const;    

   128 

   129     /**

   130      * Specific cancel for stopping ongoing message retransmission.

   131      * Response is waited as long as transaction waiting time expires.

   132      * Client is notified by calling

   133      * MSTUNClientObserver::STUNBindingErrorOccurred.

   134      *

   135      * @since   s60 v3.2

   136      * @return  void

   137      */

   138     IMPORT_C void CancelRetransmission();

   139     

   140     /**

   141      * From CBinding.

   142      * Cancels a previously issued SendRequestL.

   143      */

   144     IMPORT_C void CancelRequest();

   145     

   146     /**

   147      * From CBinding

   148      * Send binding indication. Indications are not

   149      * retransmitted and responses are not expected.

   150      *

   151      * @since   s60 v3.2

   152      * @param   aRemoteAddr     address to send to (remote agent).

   153      * @param   aAddFingerprint add fingerprint attribute if true

   154      * @return  void

   155      */

   156     IMPORT_C void SendIndicationL( const TInetAddr& aRemoteAddr,

   157         const TDesC8& aData, TBool aAddFingerprint );

   158     

   159     /**

   160      * From CBinding.

   161      * Checks whether the public address has a value set.

   162      *

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

   164      *          otherwise EFalse. 

   165      */

   166     IMPORT_C TBool AddressResolved() const;    

   167 

   168     /**

   169      * From CBinding.

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

   171      * If AddressResolved function returns EFalse, the return value of

   172      * this function is not defined.

   173      *

   174      * @return  public transport address

   175      */

   176     IMPORT_C const TInetAddr& PublicAddr() const;

   177 

   178     /**

   179      * From CBinding.

   180      * This method should be called when receiving data

   181      * from the socket shared with this binding and 

   182      * the data cannot be handled by client.

   183      *

   184      * @param   aData data received

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

   186      *          otherwise EFalse.

   187      * @param   aRemoteAddr remote address from remote address attribute

   188      * @return  Decoded data if data is indication and not unsaf message,

   189      *          otherwise NULL. Ownership is transferred.

   190      */

   191     IMPORT_C HBufC8* HandleDataL( 

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

   193     

   194     /**

   195      * From CBinding.

   196      * ICE specific attributes can be set for the request.

   197      *  

   198      * @since   s60 v3.2

   199      * @param   aAttributes     Contains ICE specific attributes.

   200      * @return  void

   201      */

   202     IMPORT_C void SetICESpecificAttributes(

   203         const TICEAttributes& aAttributes );

   204         

   205     /**

   206      * From CBinding.

   207      * Query used stream ID

   208      *

   209      * @since   s60 v3.2

   210      * @return  stream Id

   211      */

   212     IMPORT_C TUint StreamId() const;

   213     

   214     /**

   215      * From CBinding.

   216      * Query used connection ID

   217      *

   218      * @since   s60 v3.2

   219      * @return  connection Id

   220      */

   221     IMPORT_C TUint ConnectionId() const;

   222 

   223     /**

   224      * From CBinding.

   225      * Returns alternate server transport address.

   226      *

   227      * @since   s60 v3.2

   228      * @return  alternate server address

   229      */

   230     IMPORT_C const TInetAddr& AlternateServerAddr() const;

   231     

   232     /**

   233      * From CBinding.

   234      * Returns realm value from error response.

   235      *

   236      * @since   s60 v3.2

   237      * @return  realm from error response         

   238      */

   239     IMPORT_C const HBufC8* RealmFromResponse() const;    

   240         

   241     /**

   242      * From CBinding.

   243      * Returns the associated CSTUNClient instance.

   244      *

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

   246      */

   247     IMPORT_C const CSTUNClient* STUNClient() const;

   248     

   249 protected:

   250 

   251     /**

   252      * From CBinding.

   253      * Returns the implementation instance.        

   254      */

   255     CBindingImplementation& Implementation();

   256     

   257     /**

   258      * From CBinding.

   259      * Returns a non-modifiable implementation instance.        

   260      */

   261     const CBindingImplementation& Implementation() const;

   262 

   263 private:

   264 

   265     CSTUNBinding();

   266     CSTUNBinding( const CBinding& aBinding );

   267 

   268     void ConstructL( CSTUNClient& aSTUNClient, RSocket& aSocket );

   269     void ConstructL( CSTUNClient& aSTUNClient, TUint aStreamId, 

   270         TUint aConnectionId );

   271 

   272     __DECLARE_TEST;

   273     };

   274 

   275 #endif // CSTUNBINDING_H

   276