/*

* 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 call class, Contains methods common for a call.

*

*/

#ifndef MCCPCALL_H

#define MCCPCALL_H

//  INCLUDES

#include <e32base.h>

#include <mccpcallobserver.h>

#include <ccpdefs.h>

#include <cccpcallparameters.h>

class MCCPConferenceCall;

class MCCPConferenceCallObserver;

class MCCPTransferProvider;

class MCCPTransferObserver;

class MCCPForwardProvider;

class MCCPForwardObserver;

/**

* All common methods for different calls.

* Events, errors, status notifications etc are received via MCCPCallObserver class

*

*  @since S60 3.2

*/

class MCCPCall

    {

protected:

    /** 

    * Protected destructor. Object cannot be deleted from plug-in client (CCE).

    * @since S60 3.2

    */

    virtual inline ~MCCPCall() {};

public:

    /**

    * Answer an incoming call. 

    * Returns any error asyncronous via MCCPCallObserver.

    * 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. In that case plug-in must return 

    * MCCPCallObserver::ECCPStateAnswering.

    * @return KErrNotReady if call is not in ringing or queued state.

    * @return KErrNotSupported if call does not support queueing. Plug-in will disconnect the call in this case.

    * @pre Call state is MCCPCallObserver::ECCPStateRinging or MCCPCallObserver::ECCPStateQueued.

    * @since S60 3.2

    */

    virtual TInt Answer() = 0;

    /**

    * Reject an incoming 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 ringing or queued state.

    * @pre Call state is MCCPCallObserver::ECCPStateRinging or MCCPCallObserver::ECCPStateQueued.

    * @since S60 3.2

    */

    virtual TInt Reject() = 0;

    /**

    * Reguests plug-in to queue the 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.

    * In case call waiting is temporarily not supported when called returns not ready indication.

    * @param None

    * @return KErrNone if request was started succesfully. 

    * @return KErrNotReady if call is not in ringing state or call waiting is not supported at the moment.

    * @pre Call state is MCCPCallObserver::ECCPStateIdle.

    * @post When succesfull, call state is changed to MCCPCallObserver::ECCPStateQueued.

    * @post If queueing is not supported by the plug-in call is disconnected by the plug-in.

    * @since S60 3.2

    */

    virtual TInt Queue() = 0;

    /**

    * Starts dialing to recipient. Recipient was set at call creation.

    * 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. In this case plug-in must return 

    * MCCPCallObserver::ECCPStateDialling.

    * @return KErrNotReady if call is not in idle state.

    * @return KErrNotSupported If call is not mobile originated.

    * @pre Call state is MCCPCallObserver::ECCPStateIdle and call type is MO.

    * @since S60 3.2

    */

    virtual TInt Dial() = 0;

    /**

    * Indicate call is ringning.

    * 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.

    * Optionally ringing state can be set for MO call too.

    * @param None

    * @return KErrNone if request was started succesfully.

    * @return KErrNotReady if call is not in idle state.

    * @pre Call state is MCCPCallObserver::ECCPStateIdle.

    * @since S60 3.2

    */

    virtual TInt Ringing() = 0;

    /**

    * Ends an ongoing call. 

    * Does not delete the call. Call is deleted when CConvergedCallProvider::ReleaseCall is called.

    * 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 call is already in idle state.

    * @pre Call state is not MCCPCallObserver::ECCPStateIdle.

    * @since S60 3.2

    */

    virtual TInt HangUp() = 0;

    /**

    * Called by CCE instead of HangUp when Dial has been called and state change to 

    * MCCPCallObserver::ECCPStateConnecting has not been received. 

    * Cancels the last ongoing request. Used for Dial only. Not supported for other actions.

    * 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. 

    * @since S60 3.2

    * @pre MCCPCall::Dial has been called and call state is MCCPCallObserver::ECCPIdle 

    */

    virtual TInt Cancel() = 0;

    /**

    * Puts 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 call is not in connected state.

    * @return KErrAlreadyExists if call is already held (MCCPCallObserver::ECCPStateHold).

    * @pre Call state is MCCPCallObserver::ECCPStateConnected or MCCPCallObserver::ECCPStateTransferring.

    * Transferring state is allowed only if previous state before transferring state was on-hold.

    * @since S60 3.2

    */

    virtual TInt Hold() = 0;

    /**

    * Resume previously held 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.

    * @return KErrAlreadyExists if call is already in connected state MCCPCallObserver::ECCPStateConnected.

    * @pre Call state is MCCPCallObserver::ECCPStateHold.

    * @since S60 3.2

    */

    virtual TInt Resume() = 0;

    /**

    * Swaps the 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 on in holded or connected state.

    * @pre Call state is MCCPCallObserver::ECCPStateHold or MCCPCallObserver::ECCPStateConnected.

    * @since S60 3.2

    */

    virtual TInt Swap() = 0;

    /**

    * Returns the remote party number or address of the call. 

    * In case returned remote party value is KNullDesC it means the remote party is

    * regarded as anonymous.

    * @since S60 3.2

    * @param None

    * @return Remote party address or number

    */

    virtual const TDesC& RemoteParty() const = 0;

    /**

    * Returns the remote party name of the call. 

    * @since S60 5.0

    * @param None

    * @return Remote party name. KNullDesC if not available.

    */

    virtual const TDesC& RemotePartyName() = 0;

    /**

    * Returns the original dialled party. The original number (e.g. including DTMF) dialled for 

    * an outgoing call.

    * Can be different than returned from MCCPCall::RemoteParty().

    * @since S60 3.2

    * @param None

    * @return Dialled party,

    */

    virtual const TDesC& DialledParty() const = 0;

    /**

    * Return boolean value if the call is forwarded or not.

    * @since S60 3.2

    * @param None.

    * @return ETrue if call is forwarded, else EFalse.

    */

    virtual TBool IsCallForwarded() const = 0;

    /**

    * Returns boolean value if the call is mobile originated or not.

    * @since S60 3.2

    * @param None.

    * @return ETrue if call is mobile originated, otherwise EFalse.

    */

    virtual TBool IsMobileOriginated() const = 0;

    /**

    * Returns the state of the call.

    * @since S60 3.2

    * @param None.

    * @return The current state of the call (MCCPCallObserver::TCCPCallState).

    */

    virtual MCCPCallObserver::TCCPCallState State() const = 0;

    /**

    * Returns UID of the plug-in used for this call

    * @since S60 3.2

    * @param None.

    * @return TUid Implementation UID of the Plug-In

    */

    virtual TUid Uid() const = 0;

    /**

    * Returns call control caps for this call.

    * This tells for CCE what call can currently do.

    * @since S60 3.2

    * @param None.

    * @return Call control caps defined in MCCPCallObserver::TCCPCallControlCaps.

    */

    virtual MCCPCallObserver::TCCPCallControlCaps Caps() const = 0;      

    /**

    * Return if call secure status is specified or not.

    * @since Series 60 5.0

    * @param None.

    * @return TBool ETrue if security is specified, else EFalse.

    */

    virtual TBool SecureSpecified() const = 0;

    /**

    * Get call's secure status.

    * @since Series 60 3.2

    * @param None.

    * @return TBool ETrue if security is enabled, else EFalse.

    */

    virtual TBool IsSecured() const = 0;

    /**

    * Set call parameters.

    * @since S60 3.2

    * @param aNewParams New call paramater information.

    * @return none

    */

    virtual void SetParameters( const CCCPCallParameters& aNewParams ) = 0;

    /**

    * Cet call parameters.

    * @since S60 3.2

    * @param None

    * @return Current call paramater information.

    */

    virtual const CCCPCallParameters& Parameters() const = 0;

    /**

    * Returns the inband tone associated to an error condition or a state transition of a call.

    * See defenition for TCCPTone.

    * @since S60 3.2

    * @param None.

    * @return TCCPTone Used tone.

    */

    virtual TCCPTone Tone() const = 0;

    /**

    * Get forward provider. Must return the already created object if called 

    * again after initial creation.

    * @since Series 60 3.2

    * @param aObserver Observer class for forward events.

    * @return Pointer to MCCPForwardProvider if forwarding is supported for the call.

    * In unsupported case does not leave but returns NULL. 

    * @leave On error case, system error code.

    */

    virtual MCCPForwardProvider* ForwardProviderL( const MCCPForwardObserver& aObserver ) = 0;

    /**

    * Get transfer provider. Must return the already created object if called 

    * again after initial creation.

    * @since Series 60 3.2

    * @param aObserver Observer class for transfer events

    * @return Pointer to MCCPTransferProvider if transfer is supported for the call. 

    * In unsupported case does not leave but returns NULL. 

    * otherwise returns NULL but does not leave.in case forwarding is not supported for the call.

    * @leave On error case, system error code.

    */

    virtual MCCPTransferProvider* TransferProviderL( const MCCPTransferObserver& aObserver ) = 0;

    /**

    * Adds a new observer for MCCECall object. Called in MT call case. In MO 

    * case observer will be given at call construction. 

    * @since S60 v3.2

    * @param aObserver Observer

    * @return None.

    * @leave system error if observer adding fails.

    */

    virtual void AddObserverL( const MCCPCallObserver& aObserver ) = 0;

    /**

    * Remove an observer.

    * @since S60 v3.2

    * @param aObserver Observer

    * @return KErrNone if removed succesfully. 

    * @return KErrNotFound if observer was not found.

    */

    virtual TInt RemoveObserver( const MCCPCallObserver& aObserver ) = 0;

    };

#endif // MCCPCALL_H

// End of File