/*
* 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          : CTransactionStore.h
* Part of       : TransactionUser
* Version       : SIP/6.0 
*
*/




/**
 @internalComponent
*/

#ifndef CTRANSACTIONSTORE_H
#define CTRANSACTIONSTORE_H

// INCLUDES
#include "SipStackServerDefs.h"

#include "MTransactionStore.h"
#include "MTransactionFinder.h"
#include "TransactionInfo.h"

#include <e32base.h>
#include <stringpool.h>

// FORWARD DECLARATIONS
class CTransactionBase;

class MTransactionOwner;
class CUserAgent;
class CUserAgentServer;
class MTransactionHeaders;

// CLASS DECLARATION

/**
 * CTransactionStore contains the information of all existing transactions.
 * This information is used for e.g. routing the incoming SIP messages to the
 * correct transaction or UA.
 */
class CTransactionStore :
    public CBase,
    public MTransactionStore,
	public MTransactionFinder	
	{
public: // Constructors and destructor

	/**
	 * Creates a new object.	 	 
	 * @return New CTransactionStore object, ownership is transferred.
	 */	
	static CTransactionStore* NewL();

	~CTransactionStore();

public: // From MTransactionStore

	TInt UpdateTransactionId(TTransactionId aOldTransactionId,
							 TTransactionId aNewTransactionId);

	void Remove(TTransactionId aTransactionId);

public: // From MTransactionFinder

	MReceiverObserver* Search(CSIPMessage& aMsg);

	void IcmpErrorL(const TInetAddr& aAddress,
					CSipConnectionMgr::TICMPError aError);	

public: // New functions

	/**
	 * Generates a new unique value to be used as a TransactionId.	 
	 * @return value New TransactionId value
	 */
	TTransactionId NewTransactionId();

	/**
	 * Stores information of a transaction.
	 * @pre aUserAgent != NULL
	 * @param aTransactionId transaction identifier
	 * @param aUserAgent UA, ownership is transferred
	 * @param aTransaction Transaction object, can be NULL. Ownership is not
	 *		  transferred,. as UA owns aTransaction.
	 * @param aMsg SIP message which initiated the transaction, can be NULL.
	 *		  Ownership is not transferred.
	 * @param aType Identifies which kind of transaction this is
	 *		  (client, server, etc.)
	 */
	void AddL(TTransactionId aTransactionId,
			  CUserAgent* aUserAgent,
			  CTransactionBase* aTransaction,
			  CSIPMessage* aMsg,
			  CTransactionBase::TTransactionType aType);

	/**
	 * Updates the information of the transaction identified by aTransactionId.
	 * @pre Transaction must exist in the CTransactionStore
	 * @param aTransactionId transaction identifier
	 * @param aTransaction New value for the transaction pointer, can be NULL.
	 *  Ownership is not transferred.
	 * @param aMsg The transaction related headers which are present in the
	 *  aMsg are copied to CTransactionStore. The possibly existing previously
	 *  stored headers discarded. This parameter can be NULL. Ownership is not
	 *  transferred.
	 * @leave KErrNotFound If no such transaction is found
	 */
	void UpdateL(TTransactionId aTransactionId,		 
				 CTransactionBase* aTransaction,
				 CSIPMessage* aMsg);

	/**
	 * Updates the To tag of the transaction identified by the aTransactionId.
	 * @pre Transaction must exists in the CTransactionStore
	 * @param aTransactionId transaction identifier
	 * @param aTag To tag
	 * @leave KErrNotFound If no such transaction is found
	 */
	void UpdateToTagL(TTransactionId aTransactionId, RStringF aTag);

	/**
	 * Clears the pointer to UA by setting it NULL.
	 * The UA is identified by aTransactionId.	 
	 * @param aTransactionId Identifies the UA
	 */
	void ClearUserAgent(TTransactionId aTransactionId);

	/**
	 * Clears the pointer to transaction by setting it NULL. Transaction is
	 * identified by aTransactionId.
	 * @param aTransactionId Identifies the transaction	 
	 */
	void ClearTransaction(TTransactionId aTransactionId);

	/**
	 * Searches the store for an UAS to match the CANCEL.	 
	 * @param aCancel IN: CANCEL request
	 * @param aCancelUAS IN: UA that is searching for an UAS to be canceled.
	 *  TransactionStore checks aCancelUAS to avoid returning the same UAS
	 *  that is handling the CANCEL request.
	 * @return UAS to be canceled, NULL if not found. Ownership isn't
	 *	transferred.
	 */
	CUserAgentServer* SearchUasToCancel(CSIPRequest& aCancel,
										const CUserAgent& aCancelUAS);	

	/**
	 * Searches the store for an UA having the specified aTransactionId.
	 * @param aTransactionId Identifies the UA
	 * @return The found UA or NULL if not found. Ownership is not transferred.
	 */
	CUserAgent* SearchById(TTransactionId aTransactionId);

	/**
	 * Checks if the SIP request is a merged request.
	 * Searches through the stored transactions for a transaction with a
	 * matching From tag, Call-ID and CSeq. Skips the specified UA which is
	 * aUserAgent requesting this search.
	 * @param aUserAgent UA asking if the request is merged
	 * @param aReq SIP request
	 * @return ETrue if the request is merged, EFalse otherwise
	 */
	TBool IsMergedRequest(const CUserAgent& aUserAgent, CSIPRequest& aReq);

	/**
	 * Copies any Record-Route headers possibly present in aReq, to the
	 * specified transaction's stored information.
	 * 
	 * @pre The transaction identified by aTransactionId must not already have
	 *	stored Record-Route headers.
	 * @post
	 *
	 * @param aTransactionId Transaction id used for identifying the
	 *	transaction, which will store the Record-Route headers.
	 * @param aReq SIP request from which the headers are copied from.
	 */
	void StoreRecordRouteHeadersL(TTransactionId aTransactionId,
								  CSIPRequest& aReq);

	/**
	 * Frees the stored Record-Route headers from the specified transaction.
	 * @param aTransactionId Transaction id used for identifying the
	 *	transaction which the Record-Route headers are freed.	 
	 */
	void FreeRecordRouteHeaders(TTransactionId aTransactionId);

	/**
	 * Copies any Contact headers possibly present in aReq, to the specified
	 * transaction's stored information.
	 * @pre The transaction identified by aTransactionId must not already have
	 *	stored Contact headers.
	 * @param aTransactionId Transaction id used for identifying the
	 *	transaction which will store the Contact headers.
	 * @param aReq SIP request from which the headers are copied from.
	 */
	void StoreContactHeadersL(TTransactionId aTransactionId,
							  CSIPRequest& aReq);

	/**
	 * Frees the stored Contact headers from the specified transaction.
	 * @param aTransactionId Transaction id used for identifying the
	 *	transaction which the Contact headers are freed.	 
	 */
	void FreeContactHeaders(TTransactionId aTransactionId);

	/**
	 * Copies certain headers from the CTransactionInfo item, identified by the
	 * aTransactionId, to the response message (aResp).
	 * @param aTransactionId Transaction id used for locating the correct
	 *	CTransactionInfo object	 
	 * @param aResp IN/OUT: SIP response message which will be filled.
	 */
	void CopyHeadersToResponseL(TTransactionId aTransactionId,
								CSIPResponse& aResp);

	/**
	 * Copies certain headers from the CTransactionInfo item, identified by the
	 * aTransactionId, to the aReq.
	 * @param aTransactionId Transaction id used for locating the
	 *	CTransactionInfo object	from which the headers are copied from.
	 * @param aReq SIP request into which the headers are copied
	 * @param aCopyRequestURI ETrue: Request-URI is copied, EFalse: otherwise
	 * @param aCopyViaHeaders ETrue: Via headers are copied, EFalse: otherwise
	 */
	void CopyHeadersToRequestL(TTransactionId aTransactionId,
							   CSIPRequest& aReq,
							   TBool aCopyRequestURI,
							   TBool aCopyViaHeaders);

	/**
	 * Retrieve the transaction related headers of the SIP message that created
	 * the transaction.
	 * @param aTransactionId Identifies the transaction whose SIP headers are
	 *	requested.
	 * @return MTransactionHeaders* Object containing the SIP headers.
	 *	Ownership is transferred. NULL if the transaction was not found.
	 */	
    MTransactionHeaders* TransactionHeadersL(TTransactionId aTransactionId);

	/**
	 * Obtains information from one transaction (not from any specific
	 * transaction). This information will be as a input to generate random
	 * tags.	 
	 * @param aTransactionId Will be filled by a transactionId value, unless
	 *	there are no stored transactions.
	 * @param aUserAgent OUT: Will be set to point to a UA object.
	 *	If there are no stored UAs, this pointer isn't set.
	 *	Ownership isn't transferred.
	 * @param aMsg OUT: Pointer to a SIP Message, might be zero if no SIP
	 *	message was available. Ownership is transferred.	 
	 */
	void RandomTaInfoL(TTransactionId& aTaId,
					   CUserAgent** aUserAgent,
					   CSIPMessage** aMsg);

    /**
	 * Returns the request method of the transaction identified by
     * aTransactionId.
	 * @pre A transaction identified by aTransactionId must exist in the store.	 
	 * @param aTransactionId TransactionId
	 * @return Request method
	 */
	RStringF RequestMethod(TTransactionId aTransactionId);

	/**
	 * Clears the MTransactionOwner pointers from the stored UA objects, which
	 * have a matching MTransactionOwner callback.	 
	 * @pre	aObserver != NULL
 	 * @param aObserver pointer to the MTransactionOwner callback. Ownership
	 *	isn't transferred.
	 * @return KErrNone if successful, KErrNotFound if no UA used the specified
	 *	aObserver callback.
	 */
	TInt ClearTransactionOwner(const MTransactionOwner* aObserver);

	/**
	 * Goes through all stored transactions using the given IAP-id and those
     * which are currently resolving the remote address, are stopped.
	 * @param aIapId IAP-id
	 * @param aReason Reason why transaction is stopped	 
	 */
	void EndResolvingTransactions(TUint32 aIapId, TInt aReason);

    /**
	 * Delete any transactions matching the IAP-id.
     * @param aIapId IAP-id
	 */
    void RemoveItemsByIapId(TUint32 aIapId);

	/**
	 * Check if there is space for a new server transaction.
     * @return ETrue New server transaction can be created
     *		   EFalse otherwise
	 */
	TBool AllowMoreServerTransactions() const;
private: // New functions, for internal use
	void ConstructL();
	CTransactionStore();

	/**
	 * Removes aItem from the list, deletes aItem's contents and the aItem.	 
	 * @pre	aItem != NULL	 
	 * @param aItem Item to delete.
	 */
	void DeleteItem(CTransactionInfo* aItem);

	/**
	 * Searches the store for a CTransactionInfo item of the transaction with
	 * the given aTransactionId.	 
	 * @param aTransactionId identifies the transaction whose information is
	 *	searched for
	 * @return Pointer to the object containing transaction's information,
	 *	NULL if no such transaction is found. Ownership isn't transferred.
	 */
	CTransactionInfo* FindTransactionInfo(TTransactionId aTransactionId);

	/**
	 * Searches the store for an object which should receive a SIP message
	 * with the Branch-ID, Sent-by value and method given as parameters.
	 * Transaction type has to also match.	 
     * @param aMsg SIP message received from remote endpoint
	 * @param aType identifies which kind of transaction this is
	 *	(client, server, etc.)
	 * @param aUserAgent IN: If non-zero: this is the UA that searches for an
	 *	UAS to be canceled. If NULL: the search is done to find a transaction
	 *  to receive an incoming SIP message. Ownership isn't transferred.     
	 * @return Pointer to the receiving interface of the object which should
	 *  receive the SIP message (the actual object can UA or transaction).
	 *	NULL if not found. Ownership is not transferred.
	 */
	MReceiverObserver* SearchByBranch(CSIPMessage& aMsg,
						 			  CTransactionBase::TTransactionType aType,
						 			  const CUserAgent* aUserAgent);

	/**
	 * Searches the store for an object which should receive the SIP request,
	 * using the To, From, CallID, CSeq, topmost Via, Request-URI.
     * Transaction type has to also match. Via Branch is not used for matching.	 
     * @param aReq SIP request received from remote endpoint
	 * @param aType identifies which kind of transaction this is	 
	 * @param aUserAgent IN: If non-NULL: the UA which is searching for an UAS
	 *	to be canceled. If NULL: the search is done to find a transaction to
	 *	receive an incoming SIP message. Ownership isn't transferred.     
	 * @return Receiving interface of the object which should receive the
     *  request (the actual object can UA or transaction). NULL if no matching
     *	object was found. Ownership isn't transferred.
	 */
	MReceiverObserver*
        SearchServerByHeaders(CSIPRequest& aReq,
							  CTransactionBase::TTransactionType aType,
							  const CUserAgent* aUserAgent);

	/**
	 * Check if all of the required headers for Transaction matching are
	 * present in the SIP message.	 
	 * @param aMsg SIP message
	 * @return ETrue if all required headers exist, EFalse otherwise.
	 */
	TBool RequiredHeadersPresent(CSIPMessage& aMsg) const;

    /**
	 * Compares the TTransactionType stored in aInfo with aType.	 
	 * @param aInfo Transaction information
     * @param aType Transaction type
     * @param aSearchCanceledUas Indicates whether the comparison is performed
     *  for searching an UAS to be canceled.
	 * @return ETrue if transaction types match, EFalse otherwise
	 */
	TBool CompareTransactionTypes(const CTransactionInfo& aInfo,
						          CTransactionBase::TTransactionType aType,
						          TBool aSearchCanceledUas) const;

    /**
	 * This function is used to return the receiver interface of the
     * transaction/UA that should be given the SIP message received from the
     * network.
     * If the SIP message is ACK and the UA, pointed by aInfo, has sent a 2xx
     * response, the transaction/UA is ignored as Via Branch must not be used
     * to find the transaction in case of ACK to a 2xx.	 
     * @param aMsg SIP message received from network.
	 * @param aInfo Information of the transaction that should receive a
     *  SIP message received from network. aInfo has been determined by an
     *  earlier search among the existing transactions.
     * @param aUserAgent If NULL, this parameter is ignored. If UA is not NULL,
     *  it is the UA that is searching for an UAS to be canceled. Used to the
     *  avoid returning the MReceiverObserver interface of the same UAS that
     *  initiated the search. Ownership isn't transferred.
	 * @return Object where the SIP message received from network should be
     *  passed next or NULL if there is no suitable object. Ownership is not
     *  transferred.
	 */
    MReceiverObserver* IgnoreAckTo2xx(const CSIPMessage& aMsg,
                                      CTransactionInfo& aInfo,
								      const CUserAgent* aUserAgent) const;

    /**
	 * This function is used to return the receiver interface of the
     * transaction/UA that should be given the SIP message received from the
     * network.	 
	 * @param aInfo Information of the transaction that should receive a
     *  SIP message received from network. aInfo has been determined by an
     *  earlier search among the existing transactions.
     * @param aUserAgent If NULL, this parameter is ignored. If UA is not NULL,
     *	it is the UA that is searching for an UAS to be canceled. Used to the
     *  avoid returning the MReceiverObserver interface of the same UAS that
     *	initiated the search. Ownership isn't transferred.     
	 * @return Object where the SIP message received from network should be
     *  passed next or NULL if there is no suitable object. Ownership is not
     *  transferred.
	 */
	MReceiverObserver* CheckResult(CTransactionInfo& aInfo,
								   const CUserAgent* aUserAgent) const;

	/**
	 * Remove item from list of transactions.
     * @param aItem Item to remove
     */
	void RemoveListItem(CTransactionInfo& aItem);
private: // Data

	// Information of all existing UAs and transactions
	TSglQue<CTransactionInfo> iList;

	// Counter for generating unique numbers to be used as TransactionIds.
	// This will eventually wrap around, but by the time that happens, it is
	// expected the old transactions using the same TransactionId values have
	// been terminated.
	TTransactionId iTransactionIdCounter;
	// Amount of UAS / server transactions in iList
	TInt iServerTransactionCount;
	// Maximum amount of UAS / server transactions in iList
	TInt iMaxServerTransactions;

	// We don't use __DECLARE_TEST because we don't want to export this function.
	void __DbgTestInvariant() const;



#ifdef CPPUNIT_TEST	
	friend class CTransactionStore_Test;	
	friend class CTransactionUser_Test;
	friend class CNormalUAC_ResolveAddress_Test;
	friend class CNormalUAC_WaitResponse_Test;
	friend class CUserAgentServer_Test;
	friend class CUserAgentClient_Test;
#endif
	};

#endif // end of CTRANSACTIONSTORE_H

// End of File