phonesrv_plat/converged_call_provider_api/inc/mccpcall.h
author Pat Downey <patd@symbian.org>
Wed, 01 Sep 2010 12:15:03 +0100
branchRCL_3
changeset 20 987c9837762f
parent 0 ff3b6d0fd310
permissions -rw-r--r--
Revert incorrect RCL_3 drop: Revision: 201033 Kit: 201035

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