1 /*

     2 * Copyright (c) 2006-2009 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 * Name          : CUserAgent.h

    16 * Part of       : TransactionUser

    17 * Version       : SIP/6.0

    18 *

    19 */

    20 

    21 

    22 

    23 

    24 /**

    25  @internalComponent

    26 */

    27 

    28 #ifndef CUSERAGENT_H

    29 #define CUSERAGENT_H

    30 

    31 // INCLUDES

    32 #include <stringpool.h>

    33 #include "Lwtimer.h"

    34 #include "TSIPTransportParams.h"

    35 

    36 #include "UserAgentBase.h"

    37 #include "SendStatus.h"

    38 #include "TimerValues.h"

    39 

    40 // FORWARD DECLARATIONS

    41 class MSipRegistrations;

    42 class MSipRegistrationContact;

    43 class MSigComp;

    44 class CSIPMessage;

    45 class CSIPFromToHeaderBase;

    46 class CURIContainer;

    47 class CDeleteMgr;

    48 class CTransactionBase;

    49 class CTransactionMgr;

    50 class CTransmitter;

    51 

    52 class MTransactionOwner;

    53 class CTransactionStore;

    54 class CUserAgentState;

    55 class CUserAgentCreateParams;

    56 class CSIPMessageUtility;

    57 class CUserAgentTimer;

    58 

    59 

    60 // CLASS DECLARATION

    61 /**

    62  * CUserAgent is a base class for all different UserAgents.

    63  */

    64 class CUserAgent :

    65     public CUserAgentBase,

    66 	public MSendStatus,

    67 	public MExpirationHandler	

    68 	{

    69 public: // Destructor

    70 

    71 	virtual ~CUserAgent();

    72 

    73 public: // From CUserAgentBase

    74 

    75 	void ReceiveL(CSIPRequest* aRequest);

    76 	void ReceiveL(CSIPResponse* aResponse);

    77 	void LeaveOccurred(TInt aReason);

    78 	const TSIPTransportParams& TransportParams() const;

    79 	void IcmpErrorL(const TInetAddr& aAddress,

    80 					CSipConnectionMgr::TICMPError aError);	

    81 	void TransactionEndsL(TInt aReason);

    82 	void Stop(TInt aReason);

    83 	TTransactionId TransactionId() const;    

    84 

    85 public:	// From MSendStatus

    86 

    87 	void SendCompleteL();

    88 	void SendFailedL(TInt aError);

    89 	void LeaveFromTransmitter(TInt aReason);

    90 

    91 public:	// From MExpirationHandler

    92 

    93 	void TimerExpiredL(TTimerId aTimerId, TAny* aTimerParam);

    94 

    95 public: // New pure virtual functions

    96 

    97 	/**

    98 	 * Determines whether the UserAgent is a server or a client side UserAgent.

    99 	 *

   100 	 * @return value ETrue if the UserAgent instance is server side UA,

   101 	 *	EFalse if it is client side UserAgent.

   102 	 */

   103 	virtual TBool IsUAS() const = 0;

   104 

   105 protected: // New pure virtual functions

   106 

   107 	/**

   108 	 * Creates a suitable transaction state machine. The actual type of the

   109      * transaction depends on the UserAgent type.

   110 	 */

   111 	virtual void CreateTransactionL() = 0;

   112 

   113 	/**

   114 	 * Returns the RegistrationId

   115 	 * @return value TRegistrationId

   116 	 */

   117 	virtual TRegistrationId RegistrationId() const = 0;

   118 

   119 public: // New functions

   120 

   121 	/**

   122 	 * Sends a SIP request.

   123 	 *

   124 	 * @pre aReq != NULL

   125 	 *

   126 	 * @param aReq SIP request, ownership is transferred.

   127      * @param aRegisterId Registration identifier

   128      * @param aRemoteTarget Remote target of the request	 

   129 	 */

   130 	void SendRequestL(CSIPRequest* aReq,

   131 					  TRegistrationId aRegisterId,

   132 					  const CURIContainer& aRemoteTarget);

   133 

   134     /**

   135 	 * Sends a SIP response.

   136 	 *

   137 	 * @pre aResp != NULL

   138 	 *

   139 	 * @param aResp SIP response, ownership is transferred.

   140 	 * @param aParams Transport parameters to use when sending the response

   141 	 */

   142 	void SendResponseL(CSIPResponse* aResp, const TSIPTransportParams& aParams);

   143 

   144 	/**

   145 	 * Initiates the CancelUAC state machine. A CANCEL request will be created,

   146 	 * based on the INVITE identified by aInviteTaId, and sent to network.	 

   147 	 *

   148 	 * @param aInviteTaId TransactionId of the INVITE client transaction to be

   149 	 *	canceled.

   150 	 */	

   151 	void SendCancelL(TTransactionId aInviteTaId);

   152 

   153 	/**

   154 	 * Returns the observer callback of the CUserAgent.

   155 	 *	 

   156 	 * @return value Callback to the upper layer, can be NULL. Ownership isn't

   157      *  transferred.

   158 	 */	

   159 	const MTransactionOwner* TransactionOwner() const;

   160 	

   161 	/**

   162 	 * Clears the MTransactionOwner callback. UserAgent won't use the callback

   163 	 * after this.

   164 	 *

   165 	 * @post iObserver = NULL	 

   166 	 */	

   167 	virtual void ClearTransactionOwner();

   168 

   169     /**

   170 	 * If UA has aTimer running, it is stopped and deleted.

   171 	 *

   172 	 * @param aTimer Timer to be deleted

   173 	 */

   174 	virtual void DeleteTimer(const CUserAgentTimer& aTimer);

   175 

   176 	/**

   177 	 * CUserAgent state machine moves to another state.

   178 	 *

   179 	 * @param aNewState State which CUserAgent will enter	 

   180 	 */

   181 	void ChangeState(const CUserAgentState& aNewState);

   182 

   183 	/**

   184 	 * Determines if the UserAgent is a client side INVITE UserAgent.

   185 	 *

   186 	 * @return value ETrue: the UserAgent instance is a client side INVITE

   187 	 *	UserAgent. EFalse: otherwise

   188 	 */

   189 	virtual TBool IsInviteUAC() const;

   190 

   191 	/**

   192 	 * Checks if the UserAgent is an InviteUAC created for handling an

   193 	 * additional ACK passed from the upper layer.

   194 	 *

   195 	 * @return value ETrue: this is a "sub InviteUAC", EFalse: otherwise

   196 	 */	

   197 	virtual TBool IsSubInviteUAC() const;

   198 

   199 	/**

   200 	 * Stores the message (aMsg) into UserAgent's send buffer (iOutgoingMsg).

   201 	 * The possibly existing previous message is deleted from the send buffer.

   202 	 *

   203 	 * @pre aMsg != NULL

   204 	 * @post iOutgoingMsg == aMsg

   205 	 *

   206 	 * @param aMsg SIP message, ownership is transferred	 

   207 	 */

   208 	void StoreOutgoingMsg(CSIPMessage* aMsg);

   209 		

   210 	/**

   211 	 * Sends the SIP message to MTransactionOwner.	 

   212 	 *

   213 	 * @pre aMsg != NULL	 

   214 	 *

   215 	 * @param aMsg SIP message. ownership is transferred.	 

   216 	 */

   217 	virtual void PassMsgToTransactionOwnerL(CSIPMessage* aMsg) const;

   218 

   219     /**

   220      * Checks if there are Contact headers in the SIP message (aMsg). If a

   221      * Contact header without host is found, Registration subsystem is asked to

   222      * complete the Contact header.

   223 	 *

   224      * @param aMsg SIP message

   225      * @param aFromToHeader Either a From- or To-header of the aMsg (depends on

   226      *  whether a UAC or UAS is using this method). Will be given to

   227      *  Registration subsystem in case it needs to complete a Contact header.

   228 	 * @return value -

   229 	 */

   230     void CheckContactHeadersL(CSIPMessage& aMsg,

   231                               const CSIPFromToHeaderBase* aFromToHeader) const;

   232 

   233 	/**

   234 	 * Removes transaction's information from CTransactionStore but doesn't

   235 	 * delete the CUserAgent and CTransaction objects.

   236 	 * As the transaction is no longer in CTransactionStore, it can't receive

   237 	 * any longer events from ServerCore nor any incoming SIP messages.	 

   238 	 */

   239 	void RemoveFromStore() const;

   240 	

   241 	/**

   242 	 * Sets a new value for MTransactionOwner callback, replacing the previous

   243 	 * value.

   244 	 *

   245 	 * @pre aNewObserver != NULL	 

   246 	 *

   247 	 * @param aNewObserver Callback object	 

   248 	 */

   249 	void UpdateTransactionOwner(MTransactionOwner* aNewObserver);

   250 

   251 	/**

   252 	 * Uses DeleteMgr to free CTransaction. If not successful, leaves with

   253      * a system wide error code.

   254 	 *

   255 	 * @post iTransaction == NULL	 

   256 	 */

   257 	void RequestDeletionOfTransactionL();

   258 

   259     /**

   260 	 * Returns pointer to the associated transaction instance.

   261 	 *

   262 	 * @return value Pointer to transaction or NULL if no transaction is

   263      *  associated with the UserAgent. Ownership isn't transferred.

   264 	 */

   265 	CTransactionBase* Transaction();

   266 	

   267     /**

   268 	 * When CleanupStack frees the TCleanupItem, this function is called to

   269 	 * release all resources associated for the UserAgent. Not just delete the

   270 	 * UserAgent, but also remove its information from CTransactionStore.

   271      * MTransactionOwner is not notified.

   272 	 *

   273 	 * @pre aUserAgent != NULL	 

   274 	 *

   275 	 * @param aUserAgent Pointer to the UserAgent

   276 	 */

   277     static void CleanupSilently(TAny* aUserAgent);

   278 

   279 	/**

   280 	 * Tells if the UserAgent is currently waiting an address to be resolved.

   281 	 *	 

   282 	 * @return value ETrue if the UserAgent is resolving, EFalse otherwise

   283 	 */	

   284 	TBool IsResolving() const;

   285 

   286 protected:

   287 

   288 	CUserAgent(const CUserAgentCreateParams& aParams);

   289 

   290 	void ConstructL(MSipConnectionMgr& aConnectionMgr);

   291 

   292     /**

   293 	 * Returns the current state of the UserAgent.

   294      *

   295      * @return UserAgent's current state

   296 	 */

   297     const CUserAgentState& State() const;

   298 

   299 	/**

   300 	 * Adds a specified amount of random characters into the descriptor.

   301 	 *

   302 	 * @pre aLength can't be longer than the free space left in the aBuf.	 	 

   303 	 *

   304 	 * @param aBuf Descriptor into which the random characters are added. The

   305 	 *	existing characters are not overwritten.

   306 	 * @param aLength Indicates how many characters should be added to aBuf.

   307 	 *	This is often (but not always) same as the length of aBuf.

   308 	 * @param aCaseSensitive ETrue if both upper and lowercase characters are

   309 	 *	allowed to be added into aBuf. EFalse if only lowercase characters are

   310 	 *	to be used.

   311 	 */

   312 	void AddRandomStringL(TDes8& aBuf,

   313 						  TInt aLength,

   314 						  TBool aCaseSensitive) const;

   315 

   316 	/**

   317 	 * Adds a tag into the To/From header.

   318 	 *

   319 	 * @param aToFromHeader To or From header to which a tag is added	 

   320 	 */

   321 	void AddTagL(CSIPFromToHeaderBase& aToFromHeader) const;

   322 

   323     /**

   324 	 * Sets the iTransportProtocol member according to the transport protocol

   325 	 * in the top Via header of aMsg.

   326 	 *

   327 	 * @param aMsg SIP message

   328 	 * @return value ETrue: if successful, EFalse: otherwise

   329 	 */

   330 	TBool UpdateTransportProtocol(CSIPMessage& aMsg);

   331 

   332     /**

   333 	 * Checks if aUri has parameter comp=sigcomp. If it exists, but SigComp is

   334      * not installed, function leaves with KErrNotSupported.

   335 	 *

   336 	 * @param aUri URI from which the comp parameter is checked	 

   337 	 */

   338     void CheckSigCompL(const CURIContainer& aUri) const;

   339 

   340 	/**

   341 	 * Checks if the UserAgent has stopped.

   342 	 *	 

   343 	 * @return value ETrue if UserAgent has stopped, EFalse if not

   344 	 */

   345 	TBool HasStopped() const;

   346 

   347 	/**

   348 	 * Checks if the UserAgent has been canceled. Only certain types of

   349 	 * UserAgent can be canceled. The default implementation returns EFalse.

   350 	 * Those derived UserAgents that may be canceled, need to override this

   351 	 * function.

   352 	 *

   353 	 * @return EFalse

   354 	 */

   355 	virtual TBool IsCanceled() const;

   356 

   357 	/**

   358 	 * UserAgent will detach all references to the outgoing SIP message.

   359 	 * The default implementation does nothing. Derived classes may needs to

   360 	 * override the default behaviour.	 

   361 	 */

   362 	virtual void DetachOutgoingMsg();	

   363 

   364 protected: // Data

   365 

   366 	// Callback to upper layer. Not owned. NULL if the upper layer has

   367 	// indicated it doesn't want events anymore, or if UAS hasn't yet discovered

   368 	// the upper layer.

   369 	MTransactionOwner* iObserver;

   370 

   371 	// Timer services

   372 	MTimerManager& iTimers;

   373 

   374 	MSipRegistrations& iRegistrations;

   375 

   376     MSipRegistrationContact& iRegistrationContact;

   377 

   378 	// Signalling compression services

   379     MSigComp& iSigComp;

   380 

   381 	// Information about all the existing transactions

   382 	CTransactionStore& iTransactionStore;

   383 

   384 	// UA and CTransaction use the same CTransmitter as they never send

   385 	// simultaneously. Owned.

   386 	CTransmitter* iTransmitter;

   387 

   388 	// Transaction layer for creating transaction instances.

   389 	CTransactionMgr& iTransactionMgr;

   390 

   391 	// Transaction state machine, owned.

   392 	CTransactionBase* iTransaction;

   393 

   394 	// SIP message to be sent to network.

   395 	CSIPMessage* iOutgoingMsg;

   396 

   397 	// SIP message received from CTransaction (or directly from ConnectionMgr).

   398     // Owned.

   399 	// If a response is passed to SIPSec, UAC stores the response here until

   400     // SIPSec has added the authentication parameters to the original request.

   401 	// UAS stores the request here until MTransactionOwner has been obtained and

   402 	// then forwards the request to MTransactionOwner.

   403 	CSIPMessage* iIncomingMsg;

   404 

   405 	// Transport protocol currently used.

   406 	RStringF iTransportProtocol;

   407 

   408     TSIPTransportParams iTransportParams;

   409     

   410 	// Copy of the values in CTimerValueRetriever::TTimerValues, at the time the

   411 	// UA was created. Later changes to CTimerValueRetriever::TTimerValues won't

   412 	// reflect here.

   413 	TTimerValues iTimerValues;

   414 

   415     // Tells if UA owns the SIP message in iOutgoingMsg

   416 	TBool iOwnsOutgoingMsg;

   417 

   418 	// Used for asynchronous deleting.

   419 	CDeleteMgr&	iDeleteMgr;

   420 

   421 	CSIPMessageUtility& iSIPMsgUtility;

   422 	

   423 private:

   424 

   425     /**

   426 	 * Uses DeleteMgr to free UA.

   427 	 *

   428 	 * @return value KErrNone if successful, otherwise a system wide error code

   429 	 */

   430 	TInt RequestDeletionOfUserAgent();

   431 

   432 private: // Data

   433 

   434 	// Current state of the UA. Not owned.

   435 	const CUserAgentState* iState;

   436 

   437 	// Identifies a SIP transaction.

   438 	TTransactionId iTransactionId;

   439 

   440 	// ETrue if UA state machine has ended. UA is deleted soon after it has

   441 	// ended.

   442 	TBool iStopped;

   443 

   444 private: // For testing purposes

   445 

   446 	void __DbgTestInvariant() const;

   447 

   448 

   449 

   450 #ifdef CPPUNIT_TEST	

   451 	friend class CTransactionUser_Test;

   452 	friend class CUserAgent_Test;

   453 	friend class CUserAgentClient_Test;

   454 	friend class CNormalCTa_Trying_Test;

   455 	friend class CNormalUAC_ResolveAddress_Test;

   456 	friend class CNormalUAC_WaitResponse_Test;	

   457 	friend class CInviteUAC_Start_Test;

   458 	friend class CInviteUAC_ResolveAckAddress_Test;

   459     friend class CInviteUAS_Accepted_Test;

   460 	friend class ClientTransaction_Test;

   461 	friend class CServerTransaction_Test;

   462 	friend class CInviteServerTa_Test;

   463 	friend class CUserAgentServer_Test;

   464 	friend class CNormalUAS_Start_Test;

   465 	friend class CNormalUAS_GetTxOwner_Test;

   466 	friend class CTransactionStore_Test;

   467 	friend class CNormalSTa_Trying_Test;

   468 	friend class CTransactionInfo_Test;

   469 #endif

   470 	};

   471 

   472 #endif // end of CUSERAGENT_H

   473 

   474 // End of File