/*
* Copyright (c) 2005-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        : siprefresh.h
* Part of     : SIP Client
* Interface   : SDK API, SIP Client API
* Version     : 1.0
*
*/




#ifndef CSIPREFRESH_H
#define CSIPREFRESH_H

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

// FORWARD DECLARATIONS
class CSIPClientTransaction;
class CSIPMessageElements;
class MSIPRefreshAssociation;

// CLASS DECLARATION

/**
*  @publishedAll
*  @released
*
*  Class for managing SIP refresh.
*  It provides functions for getting associated sip transaction
*  and state. Class also provides functions for updating and terminating 
*  stand-alone refreshes.
*
*  Note that only stand-alone refreshes (i.e. refreshes that are not associated
*  with registration binding or dialog associations) can be terminated or
*  updated using functions defined in this class.
*
*  @lib sipclient.lib
*/
class CSIPRefresh: public CBase
	{
	public:

		/** SIP refresh states */
		enum TState
			{
			/** SIP refresh is inactive */
			EInactive,
			/** SIP refresh active */
			EActive,
			/** SIP refresh is terminated */
			ETerminated,
			/** Object is being constructed and is not yet ready for use */
			EConstructing
			};

	public: // Constructors and destructor

		/**
		* Two-phased constructor
        * @return New object. Ownership is transferred.
		*/
		IMPORT_C static CSIPRefresh* NewL();

		/**
		* Two-phased constructor
        * @return New object. Ownership is transferred.
		*/
		IMPORT_C static CSIPRefresh* NewLC();

		/**
		* Destructor
		*/
		IMPORT_C ~CSIPRefresh();

	public: // New functions

		/**
		* Gets the state of the refresh
		* @return refresh state
		*/
        IMPORT_C CSIPRefresh::TState State() const;

		/**
		* Tests if the refresh is a stand-alone refresh
		* @return ETrue if refresh is a stand-alone; EFalse otherwise
		*/
		IMPORT_C TBool IsStandAlone() const;
		
		/**
		* Gets the associated SIP transaction with this refresh.
        *
		* @return Associated SIP transaction or 0-pointer. Ownership is not
        *   transferred.
		*/
		IMPORT_C const CSIPClientTransaction* SIPTransaction() const;

		/**
		* Terminates the refresh by sending SIP request to the remote
        * destination. The new client transactation will be of the same type
        * as the first transaction associated with this request.
		* @pre State()==EActive
		* @pre IsStandAlone()==ETrue
		* @param aElements contains optional SIP message headers and body.
        *   Ownership is transferred.
		* @return SIP client transaction. Ownership is transferred.
		* @leave KErrSIPInvalidTransactionState if State() is not EActive
		*		 KErrNotFound if the CSIPRefresh is no longer associated to
        *        anything
        *        KSIPErrInvalidRegistrationState if trying to terminate a
        *        REGISTER refresh.
        *        KErrSIPInvalidDialogState if trying to terminate a dialog
        *		 association being refreshed. 
        * @capability NetworkServices
		*/
		IMPORT_C CSIPClientTransaction*
            TerminateL(CSIPMessageElements* aElements=0);

		/**
		* Updates the refresh by sending SIP request to the remote destination.
        * The new client transactation will be of the same type as the first
        * transaction associated with this request.
		* @pre State()==EActive
		* @pre IsStandAlone()==ETrue
		* @param aElements contains optional SIP message headers and body.
        *   Ownership is transferred.
		* @return SIP client transaction. Ownership is transferred.
        * @leave KErrSIPInvalidTransactionState if State() is not EActive
		*		 KErrNotFound if the CSIPRefresh is no longer associated to
        *        anything
        *        KErrSIPInvalidRegistrationState if trying to update a
        *        REGISTER refresh. 
        *        KSIPErrInvalidDialogState if trying to update a
        *        dialog association being refreshed. 
        * @capability NetworkServices
		*/
		IMPORT_C CSIPClientTransaction*
            UpdateL(CSIPMessageElements* aElements=0);

		/**
		* Compares this object to another object 
		* @param aRefresh a CSIPRefresh type object to compare
		* @return ETrue if the objects are equal otherwise EFalse
		*/
	    IMPORT_C TBool operator==(const CSIPRefresh& aRefresh) const;

		/**
		* Gets current refresh interval
		* @pre State()==CSIPRefresh::EActive
		* @return current refresh interval in seconds
		* @leave KErrSIPResourceNotAvailable if SIP server can't be contacted
		*	because a required resource has been deleted.		
		*/
		IMPORT_C TUint IntervalL() const;

		/**
		* Sets refresh interval. 
		* Note that SIP server choses the refresh interval. This function should
		* be used only if SIP server has indicated new refresh interval using
		* SIP messages that are not associated to the refresh needing the update.
		* @pre State()==CSIPRefresh::EActive
		* @pre aInterval > 0
		* @param aInterval a new interval in seconds
		* @leave KErrArgument if aInterval == 0
		* @leave KErrSIPInvalidTransactionState if State() is not EActive
		* @leave KErrSIPResourceNotAvailable if SIP server can't be contacted
		*	because a required resource has been deleted.
		*/
		IMPORT_C void SetIntervalL(TUint aInterval);

	public: // New functions, for internal use

	    TBool DoesMatch(TUint32 aRefreshId) const;

        /**
		* Associate the CSIPRefresh with another object.
		* @param aAssoc Object associated with the CSIPRefresh
		* @return ETrue if the objects are equal otherwise EFalse
		*/
        void SetRefreshOwner(MSIPRefreshAssociation& aAssoc);

        void RemoveRefreshOwner(const MSIPRefreshAssociation& aAssoc);

        void ChangeState(CSIPRefresh::TState aNextState);

        void UpdateRefreshState(TUint aStatusCode);

        TUint32 RefreshId() const;

        void SetRefreshIdIfEmpty(TUint32 aRefreshId);        

        RStringF RequestType() const;

        void SetRequestType(RStringF aType);

        void AddTransaction(CSIPClientTransaction& aTransaction);

        void RemoveTransaction();

        CSIPClientTransaction* Transaction();

	private: // Constructors

		CSIPRefresh();

		void ConstructL();

	private:

		void CheckStateL() const;
		
	private: // Data

        MSIPRefreshAssociation* iOwner;

        //Client transaction which is refreshed, not owned by CSIPRefresh.        
        CSIPClientTransaction* iClientTransaction;

		//Current state of the refresh
        TState iState;

        //RefreshId received from SIP client        
        TUint32 iRefreshId;

        //Identifies the request method which is being refreshed
        RStringF iRequestType;

	private: // For testing purposes
#ifdef CPPUNIT_TEST
	    friend class CSIP_Test;
        friend class CSIPConnection_Test;
#endif
	};

#endif