/*
* Copyright (c) 2006 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:  CCP Conference call functionality.
*
*/


#ifndef MCCPCONFERENCECALL_H
#define MCCPCONFERENCECALL_H

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

class MCCPConferenceCallObserver; 

/**
* Conference call object.
* 
* @since S60 3.2
*/
class MCCPConferenceCall
	{
protected:
    /** 
    * Protected destructor. Object cannot be deleted from plug-in client (CCE).
    * @since S60 3.2
    */
    virtual inline ~MCCPConferenceCall() {};

public:

    /**
    * Returns the service-id used for the call.
    * @since S60 3.2
    * @param None.
    * @return Service-id of the call.
    */
    virtual TUint32 ServiceId() const = 0;

    /**
    * Ends an ongoing conference call.
    * Does not delete the call. Call deletion is requested calling 
    * CConvergedCallProvider::ReleaseConferenceCall.
	* If the request cannot be started then an error will be returned immediately as return value. 
	* In succesfull case KErrNone will be returned and the requested action has been started.
    * @param None
    * @return KErrNone if request was started succesfully. 
    * @return KErrAlreadyExists if conference is already in idle state.
    * @pre Call state is not MCCPConferenceCallObserver::ECCPConferenceIdle.
    * @since S60 3.2
    */
    virtual TInt HangUp() = 0;

    /**
    * Puts conference call on hold.
	* If the request cannot be started then an error will be returned immediately as return value. 
	* In succesfull case KErrNone will be returned and the requested action has been started.
    * @param None
    * @return KErrNone if request was started succesfully.
    * @return KErrNotReady if conferencel is not in connected state.
    * @pre Call state is MCCPConferenceCallObserver::ECCPConferenceActive.
    * @since S60 3.2
    */
    virtual TInt Hold() = 0;
      
    /**
    * Resumes previously held conference call.
	* If the request cannot be started then an error will be returned immediately as return value. 
	* In succesfull case KErrNone will be returned and the requested action has been started.
    * @param None
    * @return KErrNone if request was started succesfully.
    * @return KErrNotReady if call is not in on-hold state.
    * @pre Call state is MCCPConferenceCallObserver::ECCPConferenceHold.
    * @since S60 3.2
    */
    virtual TInt Resume() = 0;

    /**
    * Swaps a connected conference call between Hold and Resume. 
	* If the request cannot be started then an error will be returned immediately as return value. 
	* In succesfull case KErrNone will be returned and the requested action has been started.
    * @param none
    * @return KErrNone if request was started succesfully. 
    * @return KErrNotReady if call is not in on-hold state or connected state
    * @pre Call state is MCCPConferenceCallObserver::ECCPConferenceHold or 
    * MCCPConferenceCallObserver::ECCPConferenceActive
    * @since S60 3.2
    */
    virtual TInt Swap() = 0;

	/**
	* Adds a new call to conference call. 
	* When plug-in regards the call as added it will notify observer about it 
	* with call added notification MCCPConferenceCallObserver::ECCPConferenceCallAdded.
	* 
	* @since S60 3.2
	* @param aCall Call to be added to conference.
	* @return None
	* @leave In case of an error system wide error code.
	* @leave KErrAlreadyExists call is already part of conference.
	* @leave KErrNotReady In case conference is not on hold or idle.
	* @pre Conference call state is MCCPConferenceCallObserver::ECCPConferenceHold or 
	* MCCPConferenceCallObserver::ECCPConferenceIdle. 
	* @post Added call is notified calling MCCPConferenceCallObserver::ConferenceCallEventOccurred.
	* @post If conference becomes active regarding its internal plug-in based logic state is 
	* MCCPConferenceCallObserver::ECCPConferenceActive.
	*/
	virtual void AddCallL( MCCPCall* aCall ) = 0;

	/**
	* Removes a call from conference call. Can be called on any state.
	* When plug-in regards the call as removed it will notify observer about it 
	* with call removed notification MCCPConferenceCallObserver::ECCPConferenceCallRemoved.
	* @since S60 3.2
	* @param aCall Call to be removed from conference.
	* @return None
	* @leave In case of an error system wide error code.
	* @leave KErrNotFound call was not part of conference.
	* @leave KErrNotReady In case conference is not connected (MCCPConferenceCallObserver::ECCPConferenceActive) state.
	* @pre Conference call state is MCCPConferenceCallObserver::ECCPConferenceActive or 
	* MCCPConferenceCallObserver::ECCPConferenceIdle. 
	* @post Removed call is notified calling MCCPConferenceCallObserver::ConferenceCallEventOccurred.
	* @post If conference becomes idle regarding its internal plug-in based logic state is 
	* MCCPConferenceCallObserver::ECCPConferenceIdle. 
	*/
	virtual void RemoveCallL( MCCPCall* aCall ) = 0;

	/**
	* Returns number of calls active calls in the conference.
	* @since S60 3.2
	* @param None
	* @return aCallCount Number of calls in conference.
	*/
	virtual TInt CallCount() const = 0;

    /**
	* Switch to a private call with given call that is part of conference. When call is regared 
	* as removed from conference it will be notified using 
	* MCCPConferenceCallObserver::ECCPConferenceCallRemoved.
	* @since S60 3.2
	* @param aCall Call to go one-to-one with.
	* @return None
	* @leave KErrNotFound call was not part of conference.
	* @post After successful actions conference call state is MCCPConferenceCallObserver::ECCPConferenceHold 
	* and private call will become active one. 
	*/
	virtual void GoOneToOneL( MCCPCall& aCall ) = 0;

    /**
	* Add all current calls in the plug-in to conference. Each succesfully added call will 
	* be separately notified using MCCPConferenceCallObserver::ECCPConferenceCallAdded.
	* If call is not added to conference it is not notified and can be regareded as not 
	* part of conference
	* @since S60 3.2
	* @param None
	* @return None
	* @leave In case of an error system wide error code.
	*/
	virtual void CurrentCallsToConferenceL() = 0;
	
    /**
    * Gets conference participants
	* @since S60 3.2
	* @param aCallArray Reference to call array
    * @return Error code
	*/
	virtual TInt GetCallArray( RPointerArray<MCCPCall>& aCallArray ) = 0;
	
    /**
    * Add an observer for conference call related events.
    * Currently CCE will set only one observer.
    * @since S60 v3.2
    * @param aObserver Observer to be added
    * @return None
    * @leave System error if observer adding fails.
    */
    virtual void AddObserverL( const MCCPConferenceCallObserver& aObserver ) = 0;

    /**
    * Remove an observer.
    * @since S60 v3.2
    * @param none
    * @param aObserver Observer for conference.
    * @return KErrNone if removed succesfully.
    * @return KErrNotFound if observer was not found.
    */
    virtual TInt RemoveObserver( const MCCPConferenceCallObserver& aObserver ) = 0;
	};

#endif // MCCPCONFERENCECALL_H