diff -r 000000000000 -r 1bce908db942 inc/natfwstunclient.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/inc/natfwstunclient.h Tue Feb 02 01:04:58 2010 +0200 @@ -0,0 +1,247 @@ +/* +* 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: Provides STUN Client services. +* +*/ + + + + +#ifndef CSTUNCLIENT_H +#define CSTUNCLIENT_H + +#include +#include +#include "natfwstunclientdefs.h" + +class MSTUNClientObserver; +class CDeltaTimer; +class CSTUNClientImplementation; +class MNcmConnectionMultiplexer; + +/** + * A class for creating STUN bindings towards a particular STUN server. + * During the initialization resolves the STUN server address using + * DNS queries and obtains a shared secret from the STUN server + * if required. Supports also STUN relay. + * Client should set credentials if pre-provisioned ( also known as + * long term credentials ) just after NewL is called. + * MSTUNClientObserver::STUNClientInitCompleted notifies when + * STUN Client is initialized. + * + * @lib stunclient.lib + */ +class CSTUNClient : public CBase + { +public: + + /** + * Two-phased constructor. + * Starts the initialization procedures for STUN Client. + * MSTUNClientObserver::STUNClientInitCompleted gets called + * when the object is ready to be used. + * + * @param aRetransmitInterval the initial retransmit interval + * for STUN Binding Requests. + * @param aServerAddress FQDN or IP address of the STUN server. + * If FQDN, assumed to be a domain for which a SRV query + * is performed. If SRV query fails a A/AAAA query is performed. + * @param aServerPort if not zero, + * server port to be used instead of STUN default port. + * @param aServiceName Client must tell used servicename + * "stun" if STUN used, + * "stun-relay" if STUN relay used. + * @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, + * MSTUNClientObserver::STUNClientInitCompleted + * will be called with KErrNotFound, + * if no SRV records for aSTUNServer with UDP were not found. + * @param aIcmpReceiverUsed Desides whether icmp receiver is + * instantiated in STUN client + * @param aMultiplexer Connection multiplexer. + * @param aTransportProtocol Transport protocol to use. + */ + IMPORT_C static CSTUNClient* NewL( + TInt aRetransmitInterval, + const TDesC8& aServerAddress, + TUint aServerPort, + const TDesC8& aServiceName, + RSocketServ& aSocketServ, + RConnection& aConnection, + CDeltaTimer& aTimer, + MSTUNClientObserver& aObserver, + TBool aObtainSharedSecret=ETrue, + TBool aFailIfNoSRVRecordsFound=EFalse, + TBool aIcmpReceiverUsed=ETrue, + MNcmConnectionMultiplexer* aMultiplexer=NULL, + TTransportProtocol aTransportProtocol=EUdpProtocol ); + + /** + * Two-phased constructor. + * Creates a new instance of CSTUNClient for ICE connectivity checks. + * Starts the initialization procedures for STUN Client. + * MSTUNClientObserver::STUNClientInitCompleted gets called + * when the object is ready to be used. + * + * @since s60 v3.2 + * @param aRetransmitInterval the initial retransmit interval + * for STUN Binding Requests. + * @param aTimer Timer services + * @param aObserver a callback for STUN Client event notifications + * @param aMultiplexer Connection multiplexer. + * @param aTransportProtocol Used transport protocol. + */ + IMPORT_C static CSTUNClient* NewL( + TInt aRetransmitInterval, + CDeltaTimer& aTimer, + MSTUNClientObserver& aObserver, + MNcmConnectionMultiplexer* aMultiplexer=NULL, + TTransportProtocol aTransportProtocol=EUdpProtocol ); + + /** + * Two-phased constructor. + */ + IMPORT_C static CSTUNClient* NewLC( + TInt aRetransmitInterval, + const TDesC8& aServerAddress, + TUint aServerPort, + const TDesC8& aServiceName, + RSocketServ& aSocketServ, + RConnection& aConnection, + CDeltaTimer& aTimer, + MSTUNClientObserver& aObserver, + TBool aObtainSharedSecret=ETrue, + TBool aFailIfNoSRVRecordsFound=EFalse, + TBool aIcmpReceiverUsed=ETrue, + MNcmConnectionMultiplexer* aMultiplexer=NULL, + TTransportProtocol aTransportProtocol=EUdpProtocol ); + + /** + * Two-phased constructor. + */ + IMPORT_C static CSTUNClient* NewLC( + TInt aRetransmitInterval, + CDeltaTimer& aTimer, + MSTUNClientObserver& aObserver, + MNcmConnectionMultiplexer* aMultiplexer=NULL, + TTransportProtocol aTransportProtocol=EUdpProtocol ); + + /** + * Destructor. + */ + IMPORT_C ~CSTUNClient(); + + /** + * 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 + */ + IMPORT_C TBool IsInitialized() const; + + /** + * Gets the STUN server address and port used for + * when sending Binding Requests. + * + * @pre IsInitialized() == ETrue + * @leave KErrNotReady if IsInitialized() == EFalse + * @leave KErrNotFound if STUN client has no responding addresses left + * @return STUN server used to keep the NAT bindings alive + */ + IMPORT_C const TInetAddr& STUNServerAddrL() const; + + /** + * Sets credentials for the STUN server used. + * These credentials override any existing ones. They are used to + * obtain short term shared secret or act as credentials as they are. + * + * @pre aUsername's length must be larger than zero and multiple of 4. + * @pre aPassword's length must be larger than zero and multiple of 4. + * @param aUsername username + * @param aPassword password + * @return void + */ + IMPORT_C 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 + */ + IMPORT_C TBool SharedSecretObtained() const; + + /** + * Requests a new UNSAF transaction ID. ID's type is + * TNATFWUNSAFTransactionID but it is casted as a descriptor as + * only TURN Plug-in needs to obtain the ID from STUN Client API. + * + * @since s60 v3.2 + * @param aTransactionID OUT: New Transaction ID + * @return void + */ + IMPORT_C void ObtainTransactionIDL( TDesC8& aTransactionID ); + + CSTUNClientImplementation& Implementation(); + +private: + + CSTUNClient(); + + CSTUNClient( const CSTUNClient& aClient ); + + void ConstructL( 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 ); + + void ConstructL( TInt aRetransmitInterval, + CDeltaTimer& aTimer, + MSTUNClientObserver& aObserver, + MNcmConnectionMultiplexer* aMultiplexer, + TTransportProtocol aTransportProtocol ); + +private: // Data + + /** + * Implementation. + * Own. + */ + CSTUNClientImplementation* iImplementation; + +private: + + __DECLARE_TEST; + }; + +#endif // CSTUNCLIENT_H +