/*

* Copyright (c) 2007 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:  This is a class for launching CCA application. 

 *

*/

#ifndef M_MCCACONNECTION_H

#define M_MCCACONNECTION_H

#include <e32std.h>

class MCCAParameter;

/** @file mccaconnection.h

 *

 *  MCCAObserver is used to get notifications from CCA application.

 *

 *  @lib ccaclient

 *  @since S60 v5.0

 */

class MCCAObserver

    {

public:

    enum TNotifyType

        {

        /* EExitEvent is used to indicate that the CCA application has been

         * closed. Accompanied parameter aReason will either be an error code 

         * or the command id that was used to close the CCA application.

         */

        EExitEvent

        };

    /**

     * This callback is to get simple notifications from CCA application.

     *

     * @since S60 5.0

     * @param aType describes the notify type (see TNotifyType)

     * @param aReason describes the reason (see events in TNotifyType)

     */

    virtual void CCASimpleNotifyL( TNotifyType aType, TInt aReason ) = 0;

    /**

     * Returns an extension point for this interface or NULL.

     * @param aExtensionUid Uid of extension

     * @return Extension point or NULL

     */

    virtual TAny* CcaObserverExtension( 

            TUid /*aExtensionUid*/ ) { return NULL; }

protected:  // Destructor

    /**

     * Destructor.

     */

    virtual ~MCCAObserver() { }

    };

/** @file mccaconnection.h

 *  MCCAConnection is used to start a actual launching of CCA application over the AppServer framwork. 

 *  Before starting the launching, the parameter class have to be instantiated and set to ready 

 *  with the proper contact data. 

 *  @see MCCAParameter

 *

 *  Example usage of the API:  

 *  @code

 *  Header file:

 *   

 *  // Launching can be done without MCCAObserver-interface,

 *  // then the iConnection can be closed in destructor etc when

 *  // CCApplication is already closed

 *  class CMyClass : public CBase, public MCCAObserver

 *  {

 *  ...

 *  MCCAConnection* iConnection;

 *  };

 *

 *  

 *  Source file:

 *  ...

 *  // Launch the CCApplication  

 *  MCCAParameter* parameter = TCCAFactory::NewParameterL();

 *  CleanupClosePushL( *parameter );

 *  // prepare parameter here (see details from the header)

 *  if ( !iConnection )

 *      {// get connection

 *      iConnection = TCCAFactory::NewConnectionL();

 *      }

 *  // note; there can be only one CCApplication instance

 *  // running simultaneously per iConnection

 *  iConnection->LaunchAppL( *parameter );

 *  OR

 *  iConnection->LaunchAppL( *parameter, this );

 *  CleanupStack::Pop();// parameter is taken care by iConnection

 *  ...

 *  ~CMyClass::CMyClass()

 *  {

 *  ...

 *  if ( iConnection )

 *      {// close connection

 *      iConnection->Close();

 *      }

 *  } 

 *  ...

 *  // If MCCAObserver-interface is used, it could be implemented like this

 *  void CMyClass::CCASimpleNotifyL( TNotifyType aType, TInt aReason )

 *  {

 *  // check the condition of aReason here if needed

 *  if ( MCCAObserver::EExitEvent == aType )

 *      {

 *      // Calling Close() for iConnection will close the running 

 *      // CCApplication, so be careful when using it

 *      if ( iConnection )

 *          {

 *          iConnection->Close();

 *          iConnection = NULL;

 *          }

 *      }

 *  }

 *  ...

 *

 *  @endcode

 *

 *  @lib ccaclient

 *  @since S60 v5.0

 */

class MCCAConnection

    {

public:

    /**

     * Destroy this entity

     *

     * @since S60 5.0

     */

    virtual void Close() = 0;

    /**

     * DEPRECATED - USE LaunchAppL() instead!

     * Ownership of MCCAParameter is NOT transferred.

     */

    virtual void LaunchApplicationL( MCCAParameter& aParameter ) = 0;

    /**

     * Launches CCA application with the given parameter.

     * See above for example instructions.

     *

     * Ownership of MCCAParameter is transferred.

     *

     * Leaves KErrArgument if there is no contact data in the

     *        given parameter. 

     * Leaves KErrAlreadyExists if there is already CCApplication

     * running simultaneously.

     * 

     * @see MCCAParameter::SetContactDataL      

     * @since S60 5.0

     * @param aParameter to launch application

     * @param aObserver to get notifications (see MCCAObserver)

     */    

    virtual void LaunchAppL( 

        MCCAParameter& aParameter, 

        MCCAObserver* aObserver = NULL ) = 0;

    };

#endif //M_MCCACONNECTION_H

// End of File