/*

* Copyright (c) 2005 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:    

*

*/

#ifndef CMCEREFER_H

#define CMCEREFER_H

// INCLUDES

#include <e32base.h>

#include <mcedefs.h>

// FORWARD DECLARATIONS

class CDesC8Array;

class CMceEvent;

class CMceManager;

class CMceItcSender;

class TMceIds;

class CMceMsgBase;

class TMceEvent;

class CMceReferReceiver;

class CMceSession;

// CLASS DECLARATION

/**

* Base class for MCE refers, inherited by both CMceInRefer and CMceOutRefer.

*

* CMceRefer represents peer-to-peer connection made with remote terminal.

* This connection is also known as dialog and it is set up using SIP REFER

* method.

*

* MCE refers are typically used for asking remote terminal to perform

* some action. One such action is session transfer.

*

* The refer is finally terminated by the endpoint performing the action.

* Refer can implicitically also create an event which is used to inform

* how the action proceeds. In such case refer and event and tied together

* and are finally terminated simultaneously.

*

* If for any reason instance of this class is deleted while in active state,

* event is automatically terminated by MCE server.

*

*  @lib mceclient.lib

*/

class CMceRefer : public CBase

    {

    public: 

        // Refer states

        enum TState

            {

            EIdle,

            EPending, 

            EAccepted,

            ETerminated 

            };

        // Refer types

        enum TType

            {

            ENoSuppression,

            ESuppressed,

            EMultipleRefer

            };

    public: // Constructors and destructors

		/**

		* Destructor.

		*/

		virtual ~CMceRefer();

    public: // New functions

		/**

        * Returns the state of the refer.

        * @return TMceReferState, The current state of the refer.

        */

        IMPORT_C TState State() const;

        /**

        * Returns the recipient of the refer.

        * @return the recipient of the refer.

        */

        IMPORT_C const TDesC8& Recipient() const;

        /**

        * Returns the originator of the refer.

        * @return the originator of the refer.

        */

        IMPORT_C const TDesC8& Originator() const;

        /**

        * Returns the ReferTo header.

        * @return the ReferTo header.

        */

        IMPORT_C const TDesC8& ReferTo() const;

        /**

        * Returns the refer type

        * @return the Type of the refer.

        */

        IMPORT_C TType Type() const;

        /**

        * Returns the associated session, if any.

        * @return CMceSession Associated session, NULL if does not exist.

        */

        IMPORT_C CMceSession* AssociatedSession() const;

        /**

        * Returns the associated events, if any.

	    * @return RPointerArray array of associated events, ownership is transferred.

	    */

		IMPORT_C RPointerArray< CMceEvent >* AssociatedEventsL() const;

        /**

        * Returns the associated refers, if any.

	    * @return RPointerArray array of associated refers, ownership is transferred.

	    */

		IMPORT_C RPointerArray< CMceRefer >* AssociatedRefersL() const;

        /**

        * Returns truth value, is the refer in-refer or not.

        * @return TBool, the truth value.

        */

        virtual TBool IsInRefer() const = 0;

    public: // New functions, internal

	    /**

        * ID 

        * @return ID

        */

	    TUint32 Id() const;

	    /**

        * Dialog ID 

        * @return dialog ID

        */

	    TUint32 DialogId() const;

	    /**

        * Gets SIP profile id.

        * @return profile id.

        */

		TUint32 ProfileId() const;

	    /**

        * Gets sender for ITC.

        * @return ITC sender

        */

        CMceItcSender& ITCSender() const;

        /**

        * Gets manager

        * @return manager

        */

        CMceManager& Manager() const;

        /**

        * Gets the event established by this refer.

        * Ownership is not transfered.

        */ 

        CMceEvent* ReferEvent() const;

        /**

        * Detach the refer event

        */

        void DetachReferEvent();

        /**

        * Transfers the owned refer event to not event.

        * Called, when the application takes the ownership of

        * refer event.

        * @return the event, ownership is transferd

        */

        CMceEvent* TransferEventOwnership();

    public: // New functions, event handling 

        /**

        * Handles reception of event update

        * @param aId id of object whose state is needed to be updated

        */

        void EventReceivedL( TMceIds& aId );

        /**

        * Handles reception of event update

        * @param aId id of object whose state is needed to be updated

        * @param aMessage the message

        */

        void EventReceivedL( TMceIds& aId, CMceMsgBase& aMessage );

        /**

        * Handles reception of event update

        * @param aId id of object whose state is needed to be updated

        * @param aMessage the message

        * @param aContent the content

        */

        void EventReceivedL( TMceIds& aId, CMceMsgBase& aMessage, HBufC8* aContent );

        /**

        * Handling of error

        * @param aError the error

        */

        void ErrorOccuredL( TInt aError );

        /**

        * The state of the event established by this refer has changed.

        * @param aEvent the ITC event.

        */

        void EventStateChangedL( TMceEvent& aEvent );

	protected:  // New functions

	    /**

        * C++ default constructor.

        * @param aManager, reference to event manager.

        * @param aProfileId id of the sip profile used for the even

        * @param aDialogId id of the dialog

        * @param aType type of the refer

        */

        CMceRefer( CMceManager& aManager, 

                   TUint32 aProfileId,

                   TUint32 aDialogId,

                   TType aType );

	    /**

        * Prepares ids for ITC

        * @param aId ITC ids

        */

        void PrepareForITC( TMceIds& aId );

        /**

        * second-phase constructor

        */

	    void ConstructL( HBufC8* aRecipient,

            	         HBufC8* aReferTo,

            	         HBufC8* aOriginator,

            	         CDesC8Array* params );

	    /** 

	    * Resolves the proper refer state according to the state

	    * of refer event.

	    * @return state of the refer

	    */

	    TState ResolveStateL();

    private: // New functions, event handling and update

        /**

        * Traversal event handler

        * @param aEvent the event

        */

        void EventReceivedL( TMceEvent& aEvent );

        /**

        * Handles event

        * @param aEvent the event

        */

        void HandleEventL( TMceEvent& aEvent );

        /**

        * Handles state change

        * @param aEvent the event

        */

        void HandleStateChangedL( TMceEvent& aEvent );

    protected:  // Data

        /**

        * Current event state

        */

        TState iState;

        /**

        * Sender, owned

        */

        CMceItcSender* iSender;

        /**

        * Event receiver, owned

        */

        CMceReferReceiver* iReceiver;

        /**

        * Event manager,not owned

        */

        CMceManager& iManager;

        /**

        * SIP profile id

        */

        TUint32 iProfileId;

        /**

        * ID

        */

        TUint32 iId;

        /**

        * dialog id

        */

	    TUint32 iDialogId;

        /**

        * The event header

        */

        HBufC8* iReferTo;

        /**

        * The recipient

        */

        HBufC8* iRecipient;

        /**

        * The originator

        */

        HBufC8* iOriginator;

        /**

        * The event established by this REFER, not owned.

        */

        CMceEvent* iEvent; 

        /**

        * The event established by this REFER, owned.

        */

        CMceEvent* iOwnedEvent; 

        /**

        * Refer type

        */

        TType iType;

    private: // Reserved for future use

        TAny* iReserved;       

	    MCE_UNIT_TEST_DEFS

    };

#endif