diff -r 000000000000 -r 1bce908db942 natfw/natfwstunturnclient/inc/cstunclientimplementation.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/natfw/natfwstunturnclient/inc/cstunclientimplementation.h Tue Feb 02 01:04:58 2010 +0200 @@ -0,0 +1,582 @@ +/* +* Copyright (c) 2006-2007 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: +* +*/ + + + + +#ifndef C_STUNCLIENTIMPLEMENTATION_H +#define C_STUNCLIENTIMPLEMENTATION_H + +// INCLUDES +#include +#include +#include "natfwunsafserverresolver.h" +#include "natfwunsafserverresolverobserver.h" +#include "mnatfwunsaficmperrorobserver.h" +#include "msharedsecretobserver.h" +#include "mstunbindingobserver.h" +#include "cstuntimeruser.h" +#include "natfwstunclientdefs.h" + + +// FORWARD DECLARATIONS +class CDeltaTimer; +class CIcmpReceiver; +class MSTUNClientObserver; +class CSTUNClient; +class CBinding; +class CTransactionIDGenerator; +class CSTUNSharedSecret; +class CSTUNCredentials; +class CSTUNClientState; +class CSTUNClientResolvingTLS; +class CSTUNClientResolvingTCP; +class CSTUNClientResolvingUDP; +class CSTUNClientGetSharedSecret; +class CSTUNClientReady; +class CSTUNClientRenewSharedSecret; +class CAsyncCallback; +class MNcmConnectionMultiplexer; + + +// CLASS DECLARATION +/** +* This class hides the implementation STUN client from the user. +* @lib natfwstunclient.lib +*/ +class CSTUNClientImplementation : + public CSTUNTimerUser, + public MNATFWUNSAFServerResolverObserver, + public MIcmpErrorObserver, + public MSharedSecretObserver, + public MSTUNBindingObserver + { + friend class ut_cstunrelaybindingimplementation; + friend class ut_cstunclientimplementation; + + public: // Constructors and destructor + + /** + * Creates a new instance of CSTUNClientImplementation. + * Starts the initialization procedures for STUN Client. + * + * @param aClient STUN client + * @param aRetransmitInterval Retransmit interval for STUN binding + * requests + * @param aServerAddress FQDN or IP address of the STUN or TURN + * server to be used. + * @param aServerPort if not zero, + * server port to be used instead of STUN or TURN default port + * @param aServiceName Client must tell used servicename + * ("stun" or "stun-relay") because of discovery of server + * functionality + * @param aSocketServ A connected socket server session + * @param aConnection An active connection started by the client + * with RConnection::Start() + * @param aTimer Timer services + * @param aObserver A callback for STUN Client event notifications + * @param aObtainSharedSecret If ETrue obtains a shared secret + * which will be used for the STUN Binding Requests. + * If EFalse STUN Binding Requests will be sent without + * the shared secret related attributes. + * @param aFailIfNoSRVRecordsFound If ETrue, resolving fails if no SRV + * records for STUN server were found. + * @param aIcmpReceiverUsed Desides whether icmp receiver is + * instantiated in STUN client + * @param aMultiplexer instance of multiplexer. + * @param aTransportProtocol Used transport protocol. + * + * @return A new instance, ownership is transferred. + */ + static CSTUNClientImplementation* NewL( + CSTUNClient& aClient, + TInt aRetransmitInterval, + const TDesC8& aServerAddress, + TUint aServerPort, + const TDesC8& aServiceName, + RSocketServ& aSocketServ, + RConnection& aConnection, + CDeltaTimer& aTimer, + MSTUNClientObserver& aObserver, + TBool aObtainSharedSecret, + TBool aFailIfNoSRVRecordsFound, + TBool aIcmpReceiverUsed, + MNcmConnectionMultiplexer* aMultiplexer, + TTransportProtocol aTransportProtocol ); + + /** + * Creates a new instance of CSTUNClientImplementation (for + * ICE connectivity checks). + * Starts the initialization procedures for STUN Client. + * + * @param aClient STUN client + * @param aRetransmitInterval Retransmit interval for STUN binding + * requests + * @param aTimer Timer services + * @param aObserver A callback for STUN Client event notifications + * @param aMultiplexer instance of multiplexer. + * @param aTransportProtocol Used transport protocol. + * + * @return A new instance, ownership is transferred. + */ + static CSTUNClientImplementation* NewL( + CSTUNClient& aClient, + TInt aRetransmitInterval, + CDeltaTimer& aTimer, + MSTUNClientObserver& aObserver, + MNcmConnectionMultiplexer* aMultiplexer, + TTransportProtocol aTransportProtocol ); + + /** + * Destructor. + */ + ~CSTUNClientImplementation(); + + public: // From CSTUNTimerUser + + void TimerExpiredL(); + + void LeaveFromTimerExpired( TInt aError ); + + public: // From MUNSAFServerResolverObserver + + void CompletedL(); + + void ErrorOccured( TInt aError ); + + public: // From MIcmpErrorObserver + + void IcmpError( const TInetAddr& aAddress ); + + public: // From MSharedSecretObserver + + void SharedSecretObtainedL(); + + void SharedSecretErrorL( TInt aError ); + + public: // From MSTUNBindingObserver + + const CSTUNClient& STUNClient() const; + + CDeltaTimer& TimerProvider(); + + TInt RetransmitInterval() const; + + TTransportProtocol TransportProtocol() const; + + void AddressResolvedL( const CBinding& aBinding ) const; + + void ObtainSharedSecretL( CBinding& aBinding ); + + TBool SharedSecretRejectedL( const CBinding& aBinding, + const TDesC8& aUsername, + const TDesC8& aPassword ); + + TBool ObtainServerAddress( TInetAddr& aAddress ); + + void ObtainTransactionIDL( TNATFWUNSAFTransactionID& aTransactionID ); + + void AttachBindingL( const CBinding& aBinding ); + + void DetachBinding( const CBinding& aBinding ); + + void BindingErrorL( const CBinding& aBinding, TInt aError, + TBool aIsFatal ); + + void BindingEventOccurred( const CBinding& aBinding, + TSTUNCallbackInfo::TFunction aEvent ); + + void RenewSharedSecretL(); + + const TDesC8& UsernameForIndication(); + + const TDesC8& PasswordForIndication(); + + + public: // New functions + + /** + * Check whether this STUN Client has been properly initialized + * and can be used to create STUN bindings. + * @return ETrue if the client is initialized, otherwise EFalse + */ + TBool IsInitialized() const; + + /** + * Gets the STUN server address and port used for this client when + * sending Binding Requests. + * @pre IsInitialized() == ETrue + * @return STUN server used to keep the NAT bindings alive + * @leave KErrNotReady if IsInitialized() == EFalse + * @leave KErrNotFound if STUN client has no responding addresses left + */ + const TInetAddr& STUNServerAddrL() const; + + /** + * Sets credentials for the STUN server used. + * These credentials override any existing ones and are used for all + * the binding requests. + * @pre aUsername's length must be larger than zero and a multiple of 4 + * @pre aPasswd's length must be larger than zero and a multiple of 4 + * @param aUsername username + * @param aPasswd password + */ + void SetCredentialsL( const TDesC8& aUsername, + const TDesC8& aPassword ); + + /** + * Tells if the Binding Requests will be sent protected with the + * MESSAGE-INTEGRITY attribute. + * @return ETrue if message integrity is used, EFalse otherwise + */ + TBool SharedSecretObtained() const; + + /** + * Returns information telling if application has set credentials. + * @return ETrue Application has provided credentials + * EFalse Otherwise + */ + TBool HasPresetCredentials() const; + + /** + * Change the object's state. + * @param aNewState State to enter, can be NULL. Ownership is not + * transferred. + */ + void ChangeState( const CSTUNClientState* aNewState ); + + /** + * STUN client has encountered an error which it cannot ignore. + * Pass the error to NAT Traversal FW and enter "terminated" state. + * @pre aError != KErrNone + * @param aError Reason for the failure + */ + void Terminate( TInt aError ); + + + /** + * TLS resolving has been done (either successfully or failing). + * + * @since s60 v3.2 + * @return void + */ + void TlsResolvedL( ); + + /** + * TCP resolving has been done (either successfully or failing). + * @param aObtainSharedSecret ETrue if shared secret should be obtained. + * EFalse if shared secret will not be used. + */ + void TcpResolvedL( TBool aObtainSharedSecret ); + + /** + * Release resources allocated for address resolving. + */ + void FreeResolverResources(); + + /** + * Retrieve a shared secret from a STUN server, by sending a Shared + * Secret Request. + */ + void GetSharedSecretFromServerL(); + + /** + * Give the shared secret information the binding. + * @param aBinding STUN binding requesting a shared secret. + */ + void PassSharedSecretToBindingL( CBinding& aBinding ) const; + + /** + * Pass the shared secret to all bindings that are waiting it. + */ + void InformWaitingBindingsL() const; + + /** + * Error occurred while trying to obtain a shared secret. In case of a + * connection failure or timeout, check if there are more TCP addresses + * left to try. + * @pre aError != KErrNone + * @param aError Reason for the failure + */ + void HandleSharedSecretErrorL( TInt aError ); + + /** + * Check if the username and password match the values in currently used + * shared secret. + * @param aUsername Username to compare + * @param aPassword Password to compare + * @return ETrue Values match, EFalse otherwise + */ + TBool DoesSharedSecretMatch( const TDesC8& aUsername, + const TDesC8& aPassword ) const; + + /** + * Sends STUNClientInitCompleted event to upper layer, together with the + * aError status code. + * @param aError Initialization completion status + */ + void PassInitCompletedL( TInt aError ) const; + + /** + * Inform application that server rejected the provided credentials. + * @param aBinding STUN binding that used the credentials + */ + void PassCredentialsRejectedL( const CBinding& aBinding ) const; + + /** + * Start a timer to control when the shared secret expires. + */ + void StartSharedSecretTimer(); + + /** + * Multiplexer instance can be queried. + * + * @since s60 v3.2 + * @return multiplexer instance + */ + MNcmConnectionMultiplexer* MultiplexerInstance(); + + + private: // Enumerations + + enum TSTUNConstants + { + EDefaultSTUNPort = 3478 + }; + + private: // Constructors + + CSTUNClientImplementation( CSTUNClient& aClient, + TInt aRetransmitInterval, + TUint aServerPort, + RSocketServ& aSocketServ, + RConnection& aConnection, + CDeltaTimer& aTimer, + MSTUNClientObserver& aObserver, + TBool aObtainSharedSecret, + MNcmConnectionMultiplexer* aMultiplexer, + TTransportProtocol aTransportProtocol ); + + CSTUNClientImplementation( CSTUNClient& aClient, + TInt aRetransmitInterval, + CDeltaTimer& aTimer, + MSTUNClientObserver& aObserver, + MNcmConnectionMultiplexer* aMultiplexer, + TTransportProtocol aTransportProtocol ); + + CSTUNClientImplementation(); + + + CSTUNClientImplementation( + const CSTUNClientImplementation& aImplementation ); + + void ConstructL( const TDesC8& aServerAddress, + const TDesC8& aServiceName, + TBool aFailIfNoSRVRecordsFound, + TBool aIcmpReceiverUsed ); + + void ConstructL(); + + + private: // New functions, for internal use + + void ResolveAddressL( const TDesC8& aProtocol, + RArray& aResult ); + + void ResolveAddressL( const TDesC8& aProtocol, + RArray& aResult, + TUint aPort, + const TDesC8& aServiceName ); + + + /** + * Obtain STUN server's UDP addresses. + */ + void ResolveUdpL(); + + /** + * Removes the specified address from the list of STUN server's UDP + * addresses. + * @param aAddress Address to remove + */ + void RemoveAddress( const TInetAddr& aAddress ); + + private: // Data + + CSTUNClient& iClient; + + /** + * Retransmit interval + */ + TInt iRetransmitInterval; + + /** + * STUN or TURN server's port to use. After resolving, + * the correct port to use is also in the TInetAddrs stored in + * iTcpAddresses and iUdpAddresses. + */ + TUint iServerPort; + + /** + * Reference to RSocketServ + */ + RSocketServ& iSocketServer; + + /** + * Reference to RConnection + */ + RConnection& iConnection; + + /** + * Callback to upper layer + * Not owned. + */ + MSTUNClientObserver& iObserver; + + /** + * If ETrue obtains a shared secret, which will be used for the STUN + * Binding Requests. If EFalse STUN Binding Requests will be sent without + * the shared secret related attributes. + */ + TBool iObtainSharedSecret; + + /** + * Pointer to multiplexer + * Not own. + */ + MNcmConnectionMultiplexer* iMultiplexer; + + /** + * Callback dispatcher + * Own. + */ + CAsyncCallback* iAsyncCallback; + + /** + * STUN or TURN server address (FQDN or IP address). + * Exists only for the initialization phase. + * Own. + */ + HBufC8* iServerAddress; + + /** + * For resolving the STUN server address, owned. + * Exists only for the initialization phase. + * Own. + */ + CNATFWUNSAFServerResolver* iResolver; + + + /** + * The first address in the array is the currently used one. If it no + * longer responds, causing timeout, it will be removed from the array + * and the next address will be the one to use. When addresses run out, + * STUN client terminates and an error is reported to application. + */ + + /** + * Resolved STUN server TCP addresses. + */ + RArray iTcpAddresses; + + /** + * Resolved STUN server UDP addresses. + */ + RArray iUdpAddresses; + + /** + * Transaction id generator + * Own. + */ + CTransactionIDGenerator* iTransactionIDGenerator; + + /** + * Shared secret retriever. + * Own. + */ + CSTUNSharedSecret* iSharedSecret; + + /** + * Credentials set by application, can be NULL. + * Own. + */ + CSTUNCredentials* iCredentials; + + /** + * Bindings associated with this STUN client instance. The bindings are + * not owned by CSTUNClientImplementation. + */ + RPointerArray iBindings; + + /** + * icmp receiver + * Own. + */ + CIcmpReceiver* iIcmpReceiver; + + /** + * The current state of the CSTUNClientImplementation, not owned. + * If the pointer is NULL, it indicates the CSTUNClientImplementation + * has "terminated". + * Own. + */ + const CSTUNClientState* iState; + + /** + * STUN client's states + * Own. + */ + CSTUNClientResolvingTLS* iResolvingTLS; + CSTUNClientResolvingTCP* iResolvingTCP; + CSTUNClientResolvingUDP* iResolvingUDP; + CSTUNClientGetSharedSecret* iGetSharedSecret; + CSTUNClientReady* iReady; + CSTUNClientRenewSharedSecret* iRenewSharedSecret; + + /** + * Deltatimer, for shared timer services + * Own. + */ + CDeltaTimer* iTimer; + + /** + * Service name contains NAT protocol, e.g. "STUN" or "STUN-RELAY" + * Own. + */ + HBufC8* iServiceName; + + /** + * Transport protocol + */ + TTransportProtocol iTransportProtocol; + + + private: // For testing purposes + +#ifdef TEST_EUNIT + friend class CSTUNClientTest; + friend class CSTUNClientImplementationTest; + friend class CSTUNBindingTest; + friend class CAsyncCallbackTest; + friend class STUNTestUtils; +#endif + __DECLARE_TEST; + }; + +#endif // C_STUNCLIENTIMPLEMENTATION_H + +// End of File