--- /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 <e32base.h>
+#include <in_sock.h>
+#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
+