|
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: |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 |
|
20 |
|
21 #ifndef C_STUNCLIENTIMPLEMENTATION_H |
|
22 #define C_STUNCLIENTIMPLEMENTATION_H |
|
23 |
|
24 // INCLUDES |
|
25 #include <e32base.h> |
|
26 #include <in_sock.h> |
|
27 #include "natfwunsafserverresolver.h" |
|
28 #include "natfwunsafserverresolverobserver.h" |
|
29 #include "mnatfwunsaficmperrorobserver.h" |
|
30 #include "msharedsecretobserver.h" |
|
31 #include "mstunbindingobserver.h" |
|
32 #include "cstuntimeruser.h" |
|
33 #include "natfwstunclientdefs.h" |
|
34 |
|
35 |
|
36 // FORWARD DECLARATIONS |
|
37 class CDeltaTimer; |
|
38 class CIcmpReceiver; |
|
39 class MSTUNClientObserver; |
|
40 class CSTUNClient; |
|
41 class CBinding; |
|
42 class CTransactionIDGenerator; |
|
43 class CSTUNSharedSecret; |
|
44 class CSTUNCredentials; |
|
45 class CSTUNClientState; |
|
46 class CSTUNClientResolvingTLS; |
|
47 class CSTUNClientResolvingTCP; |
|
48 class CSTUNClientResolvingUDP; |
|
49 class CSTUNClientGetSharedSecret; |
|
50 class CSTUNClientReady; |
|
51 class CSTUNClientRenewSharedSecret; |
|
52 class CAsyncCallback; |
|
53 class MNcmConnectionMultiplexer; |
|
54 |
|
55 |
|
56 // CLASS DECLARATION |
|
57 /** |
|
58 * This class hides the implementation STUN client from the user. |
|
59 * @lib natfwstunclient.lib |
|
60 */ |
|
61 class CSTUNClientImplementation : |
|
62 public CSTUNTimerUser, |
|
63 public MNATFWUNSAFServerResolverObserver, |
|
64 public MIcmpErrorObserver, |
|
65 public MSharedSecretObserver, |
|
66 public MSTUNBindingObserver |
|
67 { |
|
68 friend class ut_cstunrelaybindingimplementation; |
|
69 friend class ut_cstunclientimplementation; |
|
70 |
|
71 public: // Constructors and destructor |
|
72 |
|
73 /** |
|
74 * Creates a new instance of CSTUNClientImplementation. |
|
75 * Starts the initialization procedures for STUN Client. |
|
76 * |
|
77 * @param aClient STUN client |
|
78 * @param aRetransmitInterval Retransmit interval for STUN binding |
|
79 * requests |
|
80 * @param aServerAddress FQDN or IP address of the STUN or TURN |
|
81 * server to be used. |
|
82 * @param aServerPort if not zero, |
|
83 * server port to be used instead of STUN or TURN default port |
|
84 * @param aServiceName Client must tell used servicename |
|
85 * ("stun" or "stun-relay") because of discovery of server |
|
86 * functionality |
|
87 * @param aSocketServ A connected socket server session |
|
88 * @param aConnection An active connection started by the client |
|
89 * with RConnection::Start() |
|
90 * @param aTimer Timer services |
|
91 * @param aObserver A callback for STUN Client event notifications |
|
92 * @param aObtainSharedSecret If ETrue obtains a shared secret |
|
93 * which will be used for the STUN Binding Requests. |
|
94 * If EFalse STUN Binding Requests will be sent without |
|
95 * the shared secret related attributes. |
|
96 * @param aFailIfNoSRVRecordsFound If ETrue, resolving fails if no SRV |
|
97 * records for STUN server were found. |
|
98 * @param aIcmpReceiverUsed Desides whether icmp receiver is |
|
99 * instantiated in STUN client |
|
100 * @param aMultiplexer instance of multiplexer. |
|
101 * @param aTransportProtocol Used transport protocol. |
|
102 * |
|
103 * @return A new instance, ownership is transferred. |
|
104 */ |
|
105 static CSTUNClientImplementation* NewL( |
|
106 CSTUNClient& aClient, |
|
107 TInt aRetransmitInterval, |
|
108 const TDesC8& aServerAddress, |
|
109 TUint aServerPort, |
|
110 const TDesC8& aServiceName, |
|
111 RSocketServ& aSocketServ, |
|
112 RConnection& aConnection, |
|
113 CDeltaTimer& aTimer, |
|
114 MSTUNClientObserver& aObserver, |
|
115 TBool aObtainSharedSecret, |
|
116 TBool aFailIfNoSRVRecordsFound, |
|
117 TBool aIcmpReceiverUsed, |
|
118 MNcmConnectionMultiplexer* aMultiplexer, |
|
119 TTransportProtocol aTransportProtocol ); |
|
120 |
|
121 /** |
|
122 * Creates a new instance of CSTUNClientImplementation (for |
|
123 * ICE connectivity checks). |
|
124 * Starts the initialization procedures for STUN Client. |
|
125 * |
|
126 * @param aClient STUN client |
|
127 * @param aRetransmitInterval Retransmit interval for STUN binding |
|
128 * requests |
|
129 * @param aTimer Timer services |
|
130 * @param aObserver A callback for STUN Client event notifications |
|
131 * @param aMultiplexer instance of multiplexer. |
|
132 * @param aTransportProtocol Used transport protocol. |
|
133 * |
|
134 * @return A new instance, ownership is transferred. |
|
135 */ |
|
136 static CSTUNClientImplementation* NewL( |
|
137 CSTUNClient& aClient, |
|
138 TInt aRetransmitInterval, |
|
139 CDeltaTimer& aTimer, |
|
140 MSTUNClientObserver& aObserver, |
|
141 MNcmConnectionMultiplexer* aMultiplexer, |
|
142 TTransportProtocol aTransportProtocol ); |
|
143 |
|
144 /** |
|
145 * Destructor. |
|
146 */ |
|
147 ~CSTUNClientImplementation(); |
|
148 |
|
149 public: // From CSTUNTimerUser |
|
150 |
|
151 void TimerExpiredL(); |
|
152 |
|
153 void LeaveFromTimerExpired( TInt aError ); |
|
154 |
|
155 public: // From MUNSAFServerResolverObserver |
|
156 |
|
157 void CompletedL(); |
|
158 |
|
159 void ErrorOccured( TInt aError ); |
|
160 |
|
161 public: // From MIcmpErrorObserver |
|
162 |
|
163 void IcmpError( const TInetAddr& aAddress ); |
|
164 |
|
165 public: // From MSharedSecretObserver |
|
166 |
|
167 void SharedSecretObtainedL(); |
|
168 |
|
169 void SharedSecretErrorL( TInt aError ); |
|
170 |
|
171 public: // From MSTUNBindingObserver |
|
172 |
|
173 const CSTUNClient& STUNClient() const; |
|
174 |
|
175 CDeltaTimer& TimerProvider(); |
|
176 |
|
177 TInt RetransmitInterval() const; |
|
178 |
|
179 TTransportProtocol TransportProtocol() const; |
|
180 |
|
181 void AddressResolvedL( const CBinding& aBinding ) const; |
|
182 |
|
183 void ObtainSharedSecretL( CBinding& aBinding ); |
|
184 |
|
185 TBool SharedSecretRejectedL( const CBinding& aBinding, |
|
186 const TDesC8& aUsername, |
|
187 const TDesC8& aPassword ); |
|
188 |
|
189 TBool ObtainServerAddress( TInetAddr& aAddress ); |
|
190 |
|
191 void ObtainTransactionIDL( TNATFWUNSAFTransactionID& aTransactionID ); |
|
192 |
|
193 void AttachBindingL( const CBinding& aBinding ); |
|
194 |
|
195 void DetachBinding( const CBinding& aBinding ); |
|
196 |
|
197 void BindingErrorL( const CBinding& aBinding, TInt aError, |
|
198 TBool aIsFatal ); |
|
199 |
|
200 void BindingEventOccurred( const CBinding& aBinding, |
|
201 TSTUNCallbackInfo::TFunction aEvent ); |
|
202 |
|
203 void RenewSharedSecretL(); |
|
204 |
|
205 const TDesC8& UsernameForIndication(); |
|
206 |
|
207 const TDesC8& PasswordForIndication(); |
|
208 |
|
209 |
|
210 public: // New functions |
|
211 |
|
212 /** |
|
213 * Check whether this STUN Client has been properly initialized |
|
214 * and can be used to create STUN bindings. |
|
215 * @return ETrue if the client is initialized, otherwise EFalse |
|
216 */ |
|
217 TBool IsInitialized() const; |
|
218 |
|
219 /** |
|
220 * Gets the STUN server address and port used for this client when |
|
221 * sending Binding Requests. |
|
222 * @pre IsInitialized() == ETrue |
|
223 * @return STUN server used to keep the NAT bindings alive |
|
224 * @leave KErrNotReady if IsInitialized() == EFalse |
|
225 * @leave KErrNotFound if STUN client has no responding addresses left |
|
226 */ |
|
227 const TInetAddr& STUNServerAddrL() const; |
|
228 |
|
229 /** |
|
230 * Sets credentials for the STUN server used. |
|
231 * These credentials override any existing ones and are used for all |
|
232 * the binding requests. |
|
233 * @pre aUsername's length must be larger than zero and a multiple of 4 |
|
234 * @pre aPasswd's length must be larger than zero and a multiple of 4 |
|
235 * @param aUsername username |
|
236 * @param aPasswd password |
|
237 */ |
|
238 void SetCredentialsL( const TDesC8& aUsername, |
|
239 const TDesC8& aPassword ); |
|
240 |
|
241 /** |
|
242 * Tells if the Binding Requests will be sent protected with the |
|
243 * MESSAGE-INTEGRITY attribute. |
|
244 * @return ETrue if message integrity is used, EFalse otherwise |
|
245 */ |
|
246 TBool SharedSecretObtained() const; |
|
247 |
|
248 /** |
|
249 * Returns information telling if application has set credentials. |
|
250 * @return ETrue Application has provided credentials |
|
251 * EFalse Otherwise |
|
252 */ |
|
253 TBool HasPresetCredentials() const; |
|
254 |
|
255 /** |
|
256 * Change the object's state. |
|
257 * @param aNewState State to enter, can be NULL. Ownership is not |
|
258 * transferred. |
|
259 */ |
|
260 void ChangeState( const CSTUNClientState* aNewState ); |
|
261 |
|
262 /** |
|
263 * STUN client has encountered an error which it cannot ignore. |
|
264 * Pass the error to NAT Traversal FW and enter "terminated" state. |
|
265 * @pre aError != KErrNone |
|
266 * @param aError Reason for the failure |
|
267 */ |
|
268 void Terminate( TInt aError ); |
|
269 |
|
270 |
|
271 /** |
|
272 * TLS resolving has been done (either successfully or failing). |
|
273 * |
|
274 * @since s60 v3.2 |
|
275 * @return void |
|
276 */ |
|
277 void TlsResolvedL( ); |
|
278 |
|
279 /** |
|
280 * TCP resolving has been done (either successfully or failing). |
|
281 * @param aObtainSharedSecret ETrue if shared secret should be obtained. |
|
282 * EFalse if shared secret will not be used. |
|
283 */ |
|
284 void TcpResolvedL( TBool aObtainSharedSecret ); |
|
285 |
|
286 /** |
|
287 * Release resources allocated for address resolving. |
|
288 */ |
|
289 void FreeResolverResources(); |
|
290 |
|
291 /** |
|
292 * Retrieve a shared secret from a STUN server, by sending a Shared |
|
293 * Secret Request. |
|
294 */ |
|
295 void GetSharedSecretFromServerL(); |
|
296 |
|
297 /** |
|
298 * Give the shared secret information the binding. |
|
299 * @param aBinding STUN binding requesting a shared secret. |
|
300 */ |
|
301 void PassSharedSecretToBindingL( CBinding& aBinding ) const; |
|
302 |
|
303 /** |
|
304 * Pass the shared secret to all bindings that are waiting it. |
|
305 */ |
|
306 void InformWaitingBindingsL() const; |
|
307 |
|
308 /** |
|
309 * Error occurred while trying to obtain a shared secret. In case of a |
|
310 * connection failure or timeout, check if there are more TCP addresses |
|
311 * left to try. |
|
312 * @pre aError != KErrNone |
|
313 * @param aError Reason for the failure |
|
314 */ |
|
315 void HandleSharedSecretErrorL( TInt aError ); |
|
316 |
|
317 /** |
|
318 * Check if the username and password match the values in currently used |
|
319 * shared secret. |
|
320 * @param aUsername Username to compare |
|
321 * @param aPassword Password to compare |
|
322 * @return ETrue Values match, EFalse otherwise |
|
323 */ |
|
324 TBool DoesSharedSecretMatch( const TDesC8& aUsername, |
|
325 const TDesC8& aPassword ) const; |
|
326 |
|
327 /** |
|
328 * Sends STUNClientInitCompleted event to upper layer, together with the |
|
329 * aError status code. |
|
330 * @param aError Initialization completion status |
|
331 */ |
|
332 void PassInitCompletedL( TInt aError ) const; |
|
333 |
|
334 /** |
|
335 * Inform application that server rejected the provided credentials. |
|
336 * @param aBinding STUN binding that used the credentials |
|
337 */ |
|
338 void PassCredentialsRejectedL( const CBinding& aBinding ) const; |
|
339 |
|
340 /** |
|
341 * Start a timer to control when the shared secret expires. |
|
342 */ |
|
343 void StartSharedSecretTimer(); |
|
344 |
|
345 /** |
|
346 * Multiplexer instance can be queried. |
|
347 * |
|
348 * @since s60 v3.2 |
|
349 * @return multiplexer instance |
|
350 */ |
|
351 MNcmConnectionMultiplexer* MultiplexerInstance(); |
|
352 |
|
353 |
|
354 private: // Enumerations |
|
355 |
|
356 enum TSTUNConstants |
|
357 { |
|
358 EDefaultSTUNPort = 3478 |
|
359 }; |
|
360 |
|
361 private: // Constructors |
|
362 |
|
363 CSTUNClientImplementation( CSTUNClient& aClient, |
|
364 TInt aRetransmitInterval, |
|
365 TUint aServerPort, |
|
366 RSocketServ& aSocketServ, |
|
367 RConnection& aConnection, |
|
368 CDeltaTimer& aTimer, |
|
369 MSTUNClientObserver& aObserver, |
|
370 TBool aObtainSharedSecret, |
|
371 MNcmConnectionMultiplexer* aMultiplexer, |
|
372 TTransportProtocol aTransportProtocol ); |
|
373 |
|
374 CSTUNClientImplementation( CSTUNClient& aClient, |
|
375 TInt aRetransmitInterval, |
|
376 CDeltaTimer& aTimer, |
|
377 MSTUNClientObserver& aObserver, |
|
378 MNcmConnectionMultiplexer* aMultiplexer, |
|
379 TTransportProtocol aTransportProtocol ); |
|
380 |
|
381 CSTUNClientImplementation(); |
|
382 |
|
383 |
|
384 CSTUNClientImplementation( |
|
385 const CSTUNClientImplementation& aImplementation ); |
|
386 |
|
387 void ConstructL( const TDesC8& aServerAddress, |
|
388 const TDesC8& aServiceName, |
|
389 TBool aFailIfNoSRVRecordsFound, |
|
390 TBool aIcmpReceiverUsed ); |
|
391 |
|
392 void ConstructL(); |
|
393 |
|
394 |
|
395 private: // New functions, for internal use |
|
396 |
|
397 void ResolveAddressL( const TDesC8& aProtocol, |
|
398 RArray<TInetAddr>& aResult ); |
|
399 |
|
400 void ResolveAddressL( const TDesC8& aProtocol, |
|
401 RArray<TInetAddr>& aResult, |
|
402 TUint aPort, |
|
403 const TDesC8& aServiceName ); |
|
404 |
|
405 |
|
406 /** |
|
407 * Obtain STUN server's UDP addresses. |
|
408 */ |
|
409 void ResolveUdpL(); |
|
410 |
|
411 /** |
|
412 * Removes the specified address from the list of STUN server's UDP |
|
413 * addresses. |
|
414 * @param aAddress Address to remove |
|
415 */ |
|
416 void RemoveAddress( const TInetAddr& aAddress ); |
|
417 |
|
418 private: // Data |
|
419 |
|
420 CSTUNClient& iClient; |
|
421 |
|
422 /** |
|
423 * Retransmit interval |
|
424 */ |
|
425 TInt iRetransmitInterval; |
|
426 |
|
427 /** |
|
428 * STUN or TURN server's port to use. After resolving, |
|
429 * the correct port to use is also in the TInetAddrs stored in |
|
430 * iTcpAddresses and iUdpAddresses. |
|
431 */ |
|
432 TUint iServerPort; |
|
433 |
|
434 /** |
|
435 * Reference to RSocketServ |
|
436 */ |
|
437 RSocketServ& iSocketServer; |
|
438 |
|
439 /** |
|
440 * Reference to RConnection |
|
441 */ |
|
442 RConnection& iConnection; |
|
443 |
|
444 /** |
|
445 * Callback to upper layer |
|
446 * Not owned. |
|
447 */ |
|
448 MSTUNClientObserver& iObserver; |
|
449 |
|
450 /** |
|
451 * If ETrue obtains a shared secret, which will be used for the STUN |
|
452 * Binding Requests. If EFalse STUN Binding Requests will be sent without |
|
453 * the shared secret related attributes. |
|
454 */ |
|
455 TBool iObtainSharedSecret; |
|
456 |
|
457 /** |
|
458 * Pointer to multiplexer |
|
459 * Not own. |
|
460 */ |
|
461 MNcmConnectionMultiplexer* iMultiplexer; |
|
462 |
|
463 /** |
|
464 * Callback dispatcher |
|
465 * Own. |
|
466 */ |
|
467 CAsyncCallback* iAsyncCallback; |
|
468 |
|
469 /** |
|
470 * STUN or TURN server address (FQDN or IP address). |
|
471 * Exists only for the initialization phase. |
|
472 * Own. |
|
473 */ |
|
474 HBufC8* iServerAddress; |
|
475 |
|
476 /** |
|
477 * For resolving the STUN server address, owned. |
|
478 * Exists only for the initialization phase. |
|
479 * Own. |
|
480 */ |
|
481 CNATFWUNSAFServerResolver* iResolver; |
|
482 |
|
483 |
|
484 /** |
|
485 * The first address in the array is the currently used one. If it no |
|
486 * longer responds, causing timeout, it will be removed from the array |
|
487 * and the next address will be the one to use. When addresses run out, |
|
488 * STUN client terminates and an error is reported to application. |
|
489 */ |
|
490 |
|
491 /** |
|
492 * Resolved STUN server TCP addresses. |
|
493 */ |
|
494 RArray<TInetAddr> iTcpAddresses; |
|
495 |
|
496 /** |
|
497 * Resolved STUN server UDP addresses. |
|
498 */ |
|
499 RArray<TInetAddr> iUdpAddresses; |
|
500 |
|
501 /** |
|
502 * Transaction id generator |
|
503 * Own. |
|
504 */ |
|
505 CTransactionIDGenerator* iTransactionIDGenerator; |
|
506 |
|
507 /** |
|
508 * Shared secret retriever. |
|
509 * Own. |
|
510 */ |
|
511 CSTUNSharedSecret* iSharedSecret; |
|
512 |
|
513 /** |
|
514 * Credentials set by application, can be NULL. |
|
515 * Own. |
|
516 */ |
|
517 CSTUNCredentials* iCredentials; |
|
518 |
|
519 /** |
|
520 * Bindings associated with this STUN client instance. The bindings are |
|
521 * not owned by CSTUNClientImplementation. |
|
522 */ |
|
523 RPointerArray<CBinding> iBindings; |
|
524 |
|
525 /** |
|
526 * icmp receiver |
|
527 * Own. |
|
528 */ |
|
529 CIcmpReceiver* iIcmpReceiver; |
|
530 |
|
531 /** |
|
532 * The current state of the CSTUNClientImplementation, not owned. |
|
533 * If the pointer is NULL, it indicates the CSTUNClientImplementation |
|
534 * has "terminated". |
|
535 * Own. |
|
536 */ |
|
537 const CSTUNClientState* iState; |
|
538 |
|
539 /** |
|
540 * STUN client's states |
|
541 * Own. |
|
542 */ |
|
543 CSTUNClientResolvingTLS* iResolvingTLS; |
|
544 CSTUNClientResolvingTCP* iResolvingTCP; |
|
545 CSTUNClientResolvingUDP* iResolvingUDP; |
|
546 CSTUNClientGetSharedSecret* iGetSharedSecret; |
|
547 CSTUNClientReady* iReady; |
|
548 CSTUNClientRenewSharedSecret* iRenewSharedSecret; |
|
549 |
|
550 /** |
|
551 * Deltatimer, for shared timer services |
|
552 * Own. |
|
553 */ |
|
554 CDeltaTimer* iTimer; |
|
555 |
|
556 /** |
|
557 * Service name contains NAT protocol, e.g. "STUN" or "STUN-RELAY" |
|
558 * Own. |
|
559 */ |
|
560 HBufC8* iServiceName; |
|
561 |
|
562 /** |
|
563 * Transport protocol |
|
564 */ |
|
565 TTransportProtocol iTransportProtocol; |
|
566 |
|
567 |
|
568 private: // For testing purposes |
|
569 |
|
570 #ifdef TEST_EUNIT |
|
571 friend class CSTUNClientTest; |
|
572 friend class CSTUNClientImplementationTest; |
|
573 friend class CSTUNBindingTest; |
|
574 friend class CAsyncCallbackTest; |
|
575 friend class STUNTestUtils; |
|
576 #endif |
|
577 __DECLARE_TEST; |
|
578 }; |
|
579 |
|
580 #endif // C_STUNCLIENTIMPLEMENTATION_H |
|
581 |
|
582 // End of File |