/*
* Copyright (c) 2006-2009 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:
* Name          : CUserAgent.h
* Part of       : TransactionUser
* Version       : SIP/6.0
*
*/




/**
 @internalComponent
*/

#ifndef CUSERAGENT_H
#define CUSERAGENT_H

// INCLUDES
#include <stringpool.h>
#include "Lwtimer.h"
#include "TSIPTransportParams.h"

#include "UserAgentBase.h"
#include "SendStatus.h"
#include "TimerValues.h"

// FORWARD DECLARATIONS
class MSipRegistrations;
class MSipRegistrationContact;
class MSigComp;
class CSIPMessage;
class CSIPFromToHeaderBase;
class CURIContainer;
class CDeleteMgr;
class CTransactionBase;
class CTransactionMgr;
class CTransmitter;

class MTransactionOwner;
class CTransactionStore;
class CUserAgentState;
class CUserAgentCreateParams;
class CSIPMessageUtility;
class CUserAgentTimer;


// CLASS DECLARATION
/**
 * CUserAgent is a base class for all different UserAgents.
 */
class CUserAgent :
    public CUserAgentBase,
	public MSendStatus,
	public MExpirationHandler	
	{
public: // Destructor

	virtual ~CUserAgent();

public: // From CUserAgentBase

	void ReceiveL(CSIPRequest* aRequest);
	void ReceiveL(CSIPResponse* aResponse);
	void LeaveOccurred(TInt aReason);
	const TSIPTransportParams& TransportParams() const;
	void IcmpErrorL(const TInetAddr& aAddress,
					CSipConnectionMgr::TICMPError aError);	
	void TransactionEndsL(TInt aReason);
	void Stop(TInt aReason);
	TTransactionId TransactionId() const;    

public:	// From MSendStatus

	void SendCompleteL();
	void SendFailedL(TInt aError);
	void LeaveFromTransmitter(TInt aReason);

public:	// From MExpirationHandler

	void TimerExpiredL(TTimerId aTimerId, TAny* aTimerParam);

public: // New pure virtual functions

	/**
	 * Determines whether the UserAgent is a server or a client side UserAgent.
	 *
	 * @return value ETrue if the UserAgent instance is server side UA,
	 *	EFalse if it is client side UserAgent.
	 */
	virtual TBool IsUAS() const = 0;

protected: // New pure virtual functions

	/**
	 * Creates a suitable transaction state machine. The actual type of the
     * transaction depends on the UserAgent type.
	 */
	virtual void CreateTransactionL() = 0;

	/**
	 * Returns the RegistrationId
	 * @return value TRegistrationId
	 */
	virtual TRegistrationId RegistrationId() const = 0;

public: // New functions

	/**
	 * Sends a SIP request.
	 *
	 * @pre aReq != NULL
	 *
	 * @param aReq SIP request, ownership is transferred.
     * @param aRegisterId Registration identifier
     * @param aRemoteTarget Remote target of the request	 
	 */
	void SendRequestL(CSIPRequest* aReq,
					  TRegistrationId aRegisterId,
					  const CURIContainer& aRemoteTarget);

    /**
	 * Sends a SIP response.
	 *
	 * @pre aResp != NULL
	 *
	 * @param aResp SIP response, ownership is transferred.
	 * @param aParams Transport parameters to use when sending the response
	 */
	void SendResponseL(CSIPResponse* aResp, const TSIPTransportParams& aParams);

	/**
	 * Initiates the CancelUAC state machine. A CANCEL request will be created,
	 * based on the INVITE identified by aInviteTaId, and sent to network.	 
	 *
	 * @param aInviteTaId TransactionId of the INVITE client transaction to be
	 *	canceled.
	 */	
	void SendCancelL(TTransactionId aInviteTaId);

	/**
	 * Returns the observer callback of the CUserAgent.
	 *	 
	 * @return value Callback to the upper layer, can be NULL. Ownership isn't
     *  transferred.
	 */	
	const MTransactionOwner* TransactionOwner() const;
	
	/**
	 * Clears the MTransactionOwner callback. UserAgent won't use the callback
	 * after this.
	 *
	 * @post iObserver = NULL	 
	 */	
	virtual void ClearTransactionOwner();

    /**
	 * If UA has aTimer running, it is stopped and deleted.
	 *
	 * @param aTimer Timer to be deleted
	 */
	virtual void DeleteTimer(const CUserAgentTimer& aTimer);

	/**
	 * CUserAgent state machine moves to another state.
	 *
	 * @param aNewState State which CUserAgent will enter	 
	 */
	void ChangeState(const CUserAgentState& aNewState);

	/**
	 * Determines if the UserAgent is a client side INVITE UserAgent.
	 *
	 * @return value ETrue: the UserAgent instance is a client side INVITE
	 *	UserAgent. EFalse: otherwise
	 */
	virtual TBool IsInviteUAC() const;

	/**
	 * Checks if the UserAgent is an InviteUAC created for handling an
	 * additional ACK passed from the upper layer.
	 *
	 * @return value ETrue: this is a "sub InviteUAC", EFalse: otherwise
	 */	
	virtual TBool IsSubInviteUAC() const;

	/**
	 * Stores the message (aMsg) into UserAgent's send buffer (iOutgoingMsg).
	 * The possibly existing previous message is deleted from the send buffer.
	 *
	 * @pre aMsg != NULL
	 * @post iOutgoingMsg == aMsg
	 *
	 * @param aMsg SIP message, ownership is transferred	 
	 */
	void StoreOutgoingMsg(CSIPMessage* aMsg);
		
	/**
	 * Sends the SIP message to MTransactionOwner.	 
	 *
	 * @pre aMsg != NULL	 
	 *
	 * @param aMsg SIP message. ownership is transferred.	 
	 */
	virtual void PassMsgToTransactionOwnerL(CSIPMessage* aMsg) const;

    /**
     * Checks if there are Contact headers in the SIP message (aMsg). If a
     * Contact header without host is found, Registration subsystem is asked to
     * complete the Contact header.
	 *
     * @param aMsg SIP message
     * @param aFromToHeader Either a From- or To-header of the aMsg (depends on
     *  whether a UAC or UAS is using this method). Will be given to
     *  Registration subsystem in case it needs to complete a Contact header.
	 * @return value -
	 */
    void CheckContactHeadersL(CSIPMessage& aMsg,
                              const CSIPFromToHeaderBase* aFromToHeader) const;

	/**
	 * Removes transaction's information from CTransactionStore but doesn't
	 * delete the CUserAgent and CTransaction objects.
	 * As the transaction is no longer in CTransactionStore, it can't receive
	 * any longer events from ServerCore nor any incoming SIP messages.	 
	 */
	void RemoveFromStore() const;
	
	/**
	 * Sets a new value for MTransactionOwner callback, replacing the previous
	 * value.
	 *
	 * @pre aNewObserver != NULL	 
	 *
	 * @param aNewObserver Callback object	 
	 */
	void UpdateTransactionOwner(MTransactionOwner* aNewObserver);

	/**
	 * Uses DeleteMgr to free CTransaction. If not successful, leaves with
     * a system wide error code.
	 *
	 * @post iTransaction == NULL	 
	 */
	void RequestDeletionOfTransactionL();

    /**
	 * Returns pointer to the associated transaction instance.
	 *
	 * @return value Pointer to transaction or NULL if no transaction is
     *  associated with the UserAgent. Ownership isn't transferred.
	 */
	CTransactionBase* Transaction();
	
    /**
	 * When CleanupStack frees the TCleanupItem, this function is called to
	 * release all resources associated for the UserAgent. Not just delete the
	 * UserAgent, but also remove its information from CTransactionStore.
     * MTransactionOwner is not notified.
	 *
	 * @pre aUserAgent != NULL	 
	 *
	 * @param aUserAgent Pointer to the UserAgent
	 */
    static void CleanupSilently(TAny* aUserAgent);

	/**
	 * Tells if the UserAgent is currently waiting an address to be resolved.
	 *	 
	 * @return value ETrue if the UserAgent is resolving, EFalse otherwise
	 */	
	TBool IsResolving() const;

protected:

	CUserAgent(const CUserAgentCreateParams& aParams);

	void ConstructL(MSipConnectionMgr& aConnectionMgr);

    /**
	 * Returns the current state of the UserAgent.
     *
     * @return UserAgent's current state
	 */
    const CUserAgentState& State() const;

	/**
	 * Adds a specified amount of random characters into the descriptor.
	 *
	 * @pre aLength can't be longer than the free space left in the aBuf.	 	 
	 *
	 * @param aBuf Descriptor into which the random characters are added. The
	 *	existing characters are not overwritten.
	 * @param aLength Indicates how many characters should be added to aBuf.
	 *	This is often (but not always) same as the length of aBuf.
	 * @param aCaseSensitive ETrue if both upper and lowercase characters are
	 *	allowed to be added into aBuf. EFalse if only lowercase characters are
	 *	to be used.
	 */
	void AddRandomStringL(TDes8& aBuf,
						  TInt aLength,
						  TBool aCaseSensitive) const;

	/**
	 * Adds a tag into the To/From header.
	 *
	 * @param aToFromHeader To or From header to which a tag is added	 
	 */
	void AddTagL(CSIPFromToHeaderBase& aToFromHeader) const;

    /**
	 * Sets the iTransportProtocol member according to the transport protocol
	 * in the top Via header of aMsg.
	 *
	 * @param aMsg SIP message
	 * @return value ETrue: if successful, EFalse: otherwise
	 */
	TBool UpdateTransportProtocol(CSIPMessage& aMsg);

    /**
	 * Checks if aUri has parameter comp=sigcomp. If it exists, but SigComp is
     * not installed, function leaves with KErrNotSupported.
	 *
	 * @param aUri URI from which the comp parameter is checked	 
	 */
    void CheckSigCompL(const CURIContainer& aUri) const;

	/**
	 * Checks if the UserAgent has stopped.
	 *	 
	 * @return value ETrue if UserAgent has stopped, EFalse if not
	 */
	TBool HasStopped() const;

	/**
	 * Checks if the UserAgent has been canceled. Only certain types of
	 * UserAgent can be canceled. The default implementation returns EFalse.
	 * Those derived UserAgents that may be canceled, need to override this
	 * function.
	 *
	 * @return EFalse
	 */
	virtual TBool IsCanceled() const;

	/**
	 * UserAgent will detach all references to the outgoing SIP message.
	 * The default implementation does nothing. Derived classes may needs to
	 * override the default behaviour.	 
	 */
	virtual void DetachOutgoingMsg();	

protected: // Data

	// Callback to upper layer. Not owned. NULL if the upper layer has
	// indicated it doesn't want events anymore, or if UAS hasn't yet discovered
	// the upper layer.
	MTransactionOwner* iObserver;

	// Timer services
	MTimerManager& iTimers;

	MSipRegistrations& iRegistrations;

    MSipRegistrationContact& iRegistrationContact;

	// Signalling compression services
    MSigComp& iSigComp;

	// Information about all the existing transactions
	CTransactionStore& iTransactionStore;

	// UA and CTransaction use the same CTransmitter as they never send
	// simultaneously. Owned.
	CTransmitter* iTransmitter;

	// Transaction layer for creating transaction instances.
	CTransactionMgr& iTransactionMgr;

	// Transaction state machine, owned.
	CTransactionBase* iTransaction;

	// SIP message to be sent to network.
	CSIPMessage* iOutgoingMsg;

	// SIP message received from CTransaction (or directly from ConnectionMgr).
    // Owned.
	// If a response is passed to SIPSec, UAC stores the response here until
    // SIPSec has added the authentication parameters to the original request.
	// UAS stores the request here until MTransactionOwner has been obtained and
	// then forwards the request to MTransactionOwner.
	CSIPMessage* iIncomingMsg;

	// Transport protocol currently used.
	RStringF iTransportProtocol;

    TSIPTransportParams iTransportParams;
    
	// Copy of the values in CTimerValueRetriever::TTimerValues, at the time the
	// UA was created. Later changes to CTimerValueRetriever::TTimerValues won't
	// reflect here.
	TTimerValues iTimerValues;

    // Tells if UA owns the SIP message in iOutgoingMsg
	TBool iOwnsOutgoingMsg;

	// Used for asynchronous deleting.
	CDeleteMgr&	iDeleteMgr;

	CSIPMessageUtility& iSIPMsgUtility;
	
private:

    /**
	 * Uses DeleteMgr to free UA.
	 *
	 * @return value KErrNone if successful, otherwise a system wide error code
	 */
	TInt RequestDeletionOfUserAgent();

private: // Data

	// Current state of the UA. Not owned.
	const CUserAgentState* iState;

	// Identifies a SIP transaction.
	TTransactionId iTransactionId;

	// ETrue if UA state machine has ended. UA is deleted soon after it has
	// ended.
	TBool iStopped;

private: // For testing purposes

	void __DbgTestInvariant() const;



#ifdef CPPUNIT_TEST	
	friend class CTransactionUser_Test;
	friend class CUserAgent_Test;
	friend class CUserAgentClient_Test;
	friend class CNormalCTa_Trying_Test;
	friend class CNormalUAC_ResolveAddress_Test;
	friend class CNormalUAC_WaitResponse_Test;	
	friend class CInviteUAC_Start_Test;
	friend class CInviteUAC_ResolveAckAddress_Test;
    friend class CInviteUAS_Accepted_Test;
	friend class ClientTransaction_Test;
	friend class CServerTransaction_Test;
	friend class CInviteServerTa_Test;
	friend class CUserAgentServer_Test;
	friend class CNormalUAS_Start_Test;
	friend class CNormalUAS_GetTxOwner_Test;
	friend class CTransactionStore_Test;
	friend class CNormalSTa_Trying_Test;
	friend class CTransactionInfo_Test;
#endif
	};

#endif // end of CUSERAGENT_H

// End of File