/*

* Copyright (c) 2004 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:  Abstract interface to handle client plug-ins.

*

*/

#ifndef __MCNUICLIENTPLUGIN_H

#define __MCNUICLIENTPLUGIN_H

//  INCLUDES

#include <E32Base.h>

#include <impspresenceconnectionuiconstsng.h>

//FORWARD DECLARATION

class CIMPSSAPSettings;

class MCnUiClientPlugin;

class CPEngNWSessionSlotID2;

/**

 * Factory method for client plug-in construction.

 *

 * Global factory method to create concrete

 * client plug-ins.

 *

 * @since 2.1

 * @param aClientId Which plug-in to instantiate.

 * @return New plug-in instance.

 */

GLREF_D MCnUiClientPlugin* CreateClientPluginL( TIMPSConnectionClient aClientId,

                                                CPEngNWSessionSlotID2& aNWSessionSlotID );

/**

 * Connection settings mode values

 *

 * @since 2.1

 */

enum TCnUiConnectionMode

    {

    ECnUiCMAutomatic = 0x1, ///<Connection managing mode automatic.

    ECnUiCMManual = 0x2     ///<Connection managing mode manual.

    };

// CLASS DECLARATION

/**

 * Abstract interface to handle client plug-ins.

 *

 * Connection UI calls these client plug-in methods

 * to get certain client settings or to allow the client

 * plug-in to some connection state specific processing.

 *

 * @since 2.1

 */

NONSHARABLE_CLASS( MCnUiClientPlugin )

    {

public: //New settings getters / setters

    /**

     * For future:

     * Change these getters / setters to

     * generic typeless GetParam() / SetParam() mutators.

     *

     * Both numeric and descriptor mutators are needed to

     * preserve API. And also TIMPSConnectionClient ClientId() is needed.

     *

     * Open: How to handle client specific errors / error notes?

     * Maybe it should be possible to retrieve a error text

     * for last error. It might be a problem that plug-ins are executed

     * both application / server context... ?

     */

    /**

     * Gets the plug-ins client id.

     *

     * @since 2.1

     * @return The plug-in client ID.

     */

    virtual TIMPSConnectionClient ClientID() = 0;

    /**

     * Releases dynamic resources owned by the MCnUiClientPlugin.

     *

     * This method is called by the plug-in host to free

     * MCnUiClientPlugin owned "heavy resources" like GPRS engine

     * handles etc.  It is up to client plug-in to decide how to

     * proceed with the request.

     *

     * Plug-in host uses this method to free resources

     * when Connection UI and also plug-in processing is stopped

     * for long time to wait user input.

     *

     * In practice method implementation will first cancel

     * all outstanding requests and then free resources that it can.

     *

     * @since 2.1

     */

    virtual void ReleaseDynamicResources() = 0;

    /**

     * Called in various connection processing stages to

     * determine what is client current connection mode

     * setting.

     *

     * @since 2.1

     * @return Current client connection mode from TCnUiConnectionMode.

     */

    virtual TCnUiConnectionMode CurrentConnectionModeSettingL() = 0;

    /**

     * Called to re-wake client automatic connection mode.

     *

     * @since 2.1

     */

    virtual void ReWakeAutomaticConnectionModeL() = 0;

public: //New connection open related methods

    /**

     * Called to initialize the plug-in for connection open.

     *

     * Called just before opening the network connection.

     * (aSapConnectionOpen is reported as EFalse)

     *

     * Or if the network connection is already open,

     * called before issuing the client asynchronous

     * processing (now the aSapConnectionOpen is ETrue)

     *

     * NOTE!! This initialization request might

     * come several times during one login try

     * depending the Presence Engine behaviour.

     *

     * @since 2.1

     * @param aSapConnectionOpen ETrue if the SAP connection is

     * already open. Else EFalse.

     * @param aSap The SAP settings details.

     */

    virtual void ConnectionOpenInitL( TBool aSapConnectionOpen,

                                      const CIMPSSAPSettings& aSap ) = 0;

    /**

     * Called to determine has the network server enough

     * capabilities for client type. This method is called

     * after the network connection to SAP

     * is succesfully opened.

     *

     * If client returns EFalse (IMPS Network Server doesn't

     * have enough capabilities), login procedure is immediately

     * stopped to insufficient capabilities error, and no

     * further plug-in processing methods is called.

     *

     * @since 2.1

     * @param ETrue if currently connected SAP (IMPS Network Server)

     * has enough capabilities for this client type.

     * Else EFalse.

     */

    virtual TBool VerifySapCapabilitiesL() = 0;

    /**

     * Issues the plug-in to do asynchronous processing

     * related to connection open. This is issued after

     * the plug-in has reported that the network server has

     * enough capabilities.

     *

     * Plug-in has to initialize the given request status

     * to KRequestPending state if it starts the asynchronous

     * processing.

     *

     * If Plug-in leaves from starting the asynchronous

     * processing, it is considered to mean that starting the

     * asynchronous operation failed and there isn't any

     * asynchronous operation to wait. (So leaves are not allowed

     * between real operation start and method call return.)

     *

     * @since 2.1

     * @param aStatus The request status to complete when

     * asynchronous processing is done. Needs to be

     * initialized to KRequestPending state when

     * asynchronous processing is started.

     */

    virtual void DoPostLoginProsessingL( TRequestStatus& aStatus ) = 0;

    /**

     * This method must cancels the previously started

     * post login asynchronous processing.

     *

     * NOTE!! This method implementation must be such that

     * it copes from canceling not started operations /

     * partly constructed object.

     *

     * @since 2.1

     */

    virtual void CancelPostLoginProsessing() = 0;

public: //New connection close related methods

    /**

     * Called to initialize the plug-in for connection close.

     *

     * Called just before issuing the plug-in to do

     * its pre logout processing.

     *

     * @since 2.1

     * @param aSap The SAP settings details.

     */

    virtual void ConnectionCloseInitL( const CIMPSSAPSettings& aSap ) = 0;

    /**

     * Issues the plug-in to do asynchronous processing

     * related to connection close. This processing takes

     * place before closing that actual network connection.

     *

     * Plug-in has to initialize the given request status

     * to KRequestPending state if it starts the asynchronous

     * processing.

     *

     * If Plug-in leaves from starting the asynchronous

     * processing, it is considered to mean that starting the

     * asynchronous operation failed and there isn't any

     * asynchronous operation to wait. (So leaves are not allowed

     * between real operation start and method call return.)

     *

     * @since 2.1

     * @param aStatus The request status to complete when

     * asynchronous processing is done. Needs to be

     * initialized to KRequestPending state when

     * asynchronous processing is started.

     */

    virtual void DoPreLogoutProsessingL( TRequestStatus& aStatus ) = 0;

    /**

     * This method must cancels the previously started

     * pre logout asynchronous processing.

     *

     * NOTE!! This method implementation must be such that

     * it copes from canceling not started operations /

     * partly constructed object.

     *

     * @since 2.1

     */

    virtual void CancelPreLogoutProsessing() = 0;

    /**

     * From MCnUiClientPlugin

     * Publishes commcap attribute closed

     * @see MCnUiClientPlugin

     * @since 2.1

     */

    virtual void LoginCancelledL() = 0;

public: //Destructor

    /**

     * Virtual destructor.

     *

     * Allows destruction using

     * this interface.

     */

    virtual ~MCnUiClientPlugin() {};

    };

#endif      //  __MCNUICLIENTPLUGIN_H

//  End of File