/*

* 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 ECOM interface main class.

*

*/

#ifndef CCONVERGEDCALLPROVIDER_H

#define CCONVERGEDCALLPROVIDER_H

//  INCLUDES

#include <ecom/ecom.h>

#include <e32base.h>

#include <e32std.h>

#include <e32def.h>

#include <badesca.h>

#include <ccpdefs.h>

#include <mccpcall.h>

// FORWARD DECLARATIONS

class MCCPCallObserver;

class MCCPObserver;

class MCCPSsObserver;

class MCCPEmergencyCall;

class MCCPConferenceCall;

class MCCPConferenceCallObserver;

class MCCPDTMFProvider;

class MCCPDTMFObserver;

class MCCPExtensionProvider;

class MCCPExtensionObserver;

/**

* Converged Call Provider API - main header.

* Main class in CCP. Used e.g. to create calls, access provider classes.

* MCCPObserver class is used for notifying error, state etc information.

*

*  @since S60 3.2

*/

class CConvergedCallProvider : public CBase

    {

public: 

    /**

    * Returns CCP API plug-in implementation identified by given UID.

    * @since S60 3.2

    * @param aImplementationUid CCP API interface implementation UID

    * @return Plug-in implementation pointer returned by ECOM framework.

    * @leave KErrNotFound If ECOM plug-in implementation is not found.

    * @leave KErrNoPermission If ECOM plug-in does not have required capabilities.

    * @leave Any other symbian ECOM leave code.

    */

    static CConvergedCallProvider* NewL(const TUid& aImplementationUid);

    /**

    * Destructor. Destroys the plug-in via ecom framework using iDtor_ID_Key

    * @since S60 3.2

    * @param None

    * @return None

    */

    virtual ~CConvergedCallProvider();

    /**

    * Lists all implementations for this interface.

    * @since S60 3.2

    * @param aImplementations Array containing pointers to all implementations

    * for this interface

    * @return None

    */

    static void ListImplementationsL(RImplInfoPtrArray& aImplementations);

protected:

    /**

    * @since S60 3.2

    * @param None

    * @return None

    */

    inline CConvergedCallProvider();

public: // API functions

    /**

    * Initialize CConvergedCallProvider after it is created with NewL.

    * @since S60 3.2

    * @param aServiceId service id used by convergedcallprovider

    * @param aObserver Observer class.

    * @param aSsObserver Supplementary services observer class.

    * @leave KErrAlreadyExists If this method has already been called.

    */

    virtual void InitializeL( const TUint32 aServiceId,

                              const MCCPObserver& aObserver, 

    /**

    * Initialize CConvergedCallProvider after it is created with NewL.

    * @since S60 3.2

    * @param aObserver Observer class.

    * @param aSsObserver Supplementary services observer class.

    * @leave KErrAlreadyExists If this method has already been called.

    */

    virtual void InitializeL( const MCCPObserver& aObserver, 

    /**

    * Creates a new call.

    * @since S60 3.2

    * @param aParameters Call paramaters such as servive-id used and call type.

    * @param aRecipient Recipients address/number.

    * @param aObserver Observer for the created call.

    * @return MCCPCall Always returns a call pointer if no error occurs.

    * @leave KErrAlreadyExists Call already exists.

    * @leave KErrNotReady Temporarily not able to create the requested call. E.g. maximum 

    * supported number of calls already exists (CCE will not call this if the global limit 

    * of calls is reached, this refers to plug-in own call count limit). 

    * @leave KErrNoMemory Memory error.

    * @leave KErrNotSupported Call not supported.

    * @leave KErrArgument Invalid recipient address or service id.

    * @leave Other general system error.

    * @pre Initialize has been called.

    */ 

    virtual MCCPCall* NewCallL( const CCCPCallParameters& aParameters,

    /**

    * Releases all bindings to call and deletes it. 

    * This will be called by CCE to free all the resources reserved for the call.

    * After this call CCE will not access the call object anymore and observer 

    * for the class must not be used in plug-in.

    * This operation must always succeed. If plug-in decides to pre-allocate the 

    * call object it can choose to do so, but plug-in has to make sure call is 

    * returned to the state it was before calling CConvergedCallProvider::NewCallL.

    * @param aCalltoRemove Call to remove.

    * @return KErrNone if succesfull.

    * @return KErrNotFound if removed call is not found.

    * @pre None, can always be called.

    * @post Plug-in must quarantee all resources for the call will be cleaned up 

    * and plug-in must not call observer after this call!

    * @since S60 3.2

    */

    virtual TInt ReleaseCall( MCCPCall& aCalltoRemove ) = 0;

    /**

    * Creates a new emergency call.

    * @since S60 3.2

    * @param aServiceId Service-Id (this might get removed)

    * @param aAddress Address where emergency call is to be made

    * Can be KNullDesC. Plug-in will use the given address and/or use its own information.

    * @param aObserver Observer for the emergency call.

    * @return MCCPEmergencyCall Created emergency call.

    * @pre Emergency call object is created.

    */

    virtual MCCPEmergencyCall* NewEmergencyCallL( const TUint32 aServiceId, 

                                                  const TDesC& aAddress,

                                                  const MCCPCallObserver& aObserver ) = 0;

    /**

    * Releases all bindings to call and deletes it. 

    * This must be called to free all the resources reserved for the call.

    * After this call CCE must not be access the call object anymore and observer 

    * for the class must not be used in plug-in.

    * This operation mustways succeed. If plug-in decides to pre-allocate the 

    * call object it can choose to do so, but client has to be sure call is 

    * cleared from the plug-in and all resuorces are returned to the state before calling 

    * CConvergedCallProvider::NewEmergencyCallL.

    * @param aCalltoRemove Call to remove.

    * @return KErrNone if succesfull.

    * @return KErrNotFound if removed call is not found.

    * @pre None, can always be called.

    * @post Plug-in must quarantee all resources for the call will be cleaned up. Call must not 

    * be referenced anymore from CCE and plug-in must not call observer after this call!

    * @since S60 3.2

    */

    virtual TInt ReleaseEmergencyCall( MCCPEmergencyCall& aCalltoRemove ) = 0;

    /**

    * Creates a new conference call.

    * @since S60 3.2

    * @param aServiceId Servive id used.

    * @param aObserver Conference call observer.

    * @return MCCPConferenceCall object.

    * @leave KErrNotReady Temporarily not able to create the requested conference.

    * @leave KErrNoMemory Memory error.

    * @leave KErrArgument Invalid service id.

    * @pre Initialize has been called.

    */

    virtual MCCPConferenceCall* NewConferenceL( const TUint32 aServiceId,

    /**

    * Releases all bindings to conference call. CCE will call this after receiving 

    * MCCPConferenceCallObserver::ECCPConferenceIdle from plug-in or when it itself 

    * wants to release the call. In normal sequence called from CCE after HangUp is completed.

    * @param aCalltoRemove Call to remove.

    * @return KErrNone if succesfull.

    * @return KErrNotFound if removed call is not found.

    * @pre None, can always be called.

    * @post Plug-in must quarantee all resources for the call will be cleaned up. Call must not 

    * be referenced anymore from CCE and plug-in must not call observer after this call!

    * @since S60 3.2

    */

    virtual TInt ReleaseConferenceCall( MCCPConferenceCall& aCalltoRemove ) = 0;

    /**

    * Returns the plug-in UID.

    * @since S60 3.2

    * @param None.

    * @return Plug-in UID.

    */

    virtual const TUid& Uid() const = 0;

    /**

    * Get plug-in capabilities.

    * @since Series 60 3.2

    * @param None

    * @return On return contains the capability flags of plug-In.

    */

    virtual TUint32 Caps() const = 0;

    /**

    * @since Series 60 3.2

    * @param aObserver Observer for DTMF events.

    * @pre Initialize has been called.

    * @leave KErrNoMemory Memory allocation error.

    * @leave Other general system error.

    * @param aObserver observer for extension(custom) events.

    * @pre Initialize has been called.

    * @leave KErrNoMemory Memory allocation error.

    * @leave Other general system error.

private: // Data

    // ECom indentifier key.

    TUid iDtor_ID_Key;

    };

#include <cconvergedcallprovider.inl>

#endif // CCONVERGEDCALLPROVIDER_H

// End of File