1 /*

     2 * Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Abstract interface to handle client plug-ins.

    15 *

    16 */

    17 

    18 #ifndef __MCNUICLIENTPLUGIN_H

    19 #define __MCNUICLIENTPLUGIN_H

    20 

    21 //  INCLUDES

    22 #include <E32Base.h>

    23 #include <impspresenceconnectionuiconstsng.h>

    24 

    25 

    26 //FORWARD DECLARATION

    27 class CIMPSSAPSettings;

    28 class MCnUiClientPlugin;

    29 class CPEngNWSessionSlotID2;

    30 

    31 /**

    32  * Factory method for client plug-in construction.

    33  *

    34  * Global factory method to create concrete

    35  * client plug-ins.

    36  *

    37  * @since 2.1

    38  * @param aClientId Which plug-in to instantiate.

    39  * @return New plug-in instance.

    40  */

    41 GLREF_D MCnUiClientPlugin* CreateClientPluginL( TIMPSConnectionClient aClientId,

    42                                                 CPEngNWSessionSlotID2& aNWSessionSlotID );

    43 

    44 

    45 /**

    46  * Connection settings mode values

    47  *

    48  * @since 2.1

    49  */

    50 enum TCnUiConnectionMode

    51     {

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

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

    54     };

    55 

    56 

    57 // CLASS DECLARATION

    58 /**

    59  * Abstract interface to handle client plug-ins.

    60  *

    61  * Connection UI calls these client plug-in methods

    62  * to get certain client settings or to allow the client

    63  * plug-in to some connection state specific processing.

    64  *

    65  * @since 2.1

    66  */

    67 NONSHARABLE_CLASS( MCnUiClientPlugin )

    68     {

    69 public: //New settings getters / setters

    70 

    71     /**

    72      * For future:

    73      * Change these getters / setters to

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

    75      *

    76      * Both numeric and descriptor mutators are needed to

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

    78      *

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

    80      * Maybe it should be possible to retrieve a error text

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

    82      * both application / server context... ?

    83      */

    84 

    85 

    86     /**

    87      * Gets the plug-ins client id.

    88      *

    89      * @since 2.1

    90      * @return The plug-in client ID.

    91      */

    92     virtual TIMPSConnectionClient ClientID() = 0;

    93 

    94 

    95     /**

    96      * Releases dynamic resources owned by the MCnUiClientPlugin.

    97      *

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

    99      * MCnUiClientPlugin owned "heavy resources" like GPRS engine

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

   101      * proceed with the request.

   102      *

   103      * Plug-in host uses this method to free resources

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

   105      * for long time to wait user input.

   106      *

   107      * In practice method implementation will first cancel

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

   109      *

   110      * @since 2.1

   111      */

   112     virtual void ReleaseDynamicResources() = 0;

   113 

   114     /**

   115      * Called in various connection processing stages to

   116      * determine what is client current connection mode

   117      * setting.

   118      *

   119      * @since 2.1

   120      * @return Current client connection mode from TCnUiConnectionMode.

   121      */

   122     virtual TCnUiConnectionMode CurrentConnectionModeSettingL() = 0;

   123 

   124     /**

   125      * Called to re-wake client automatic connection mode.

   126      *

   127      * @since 2.1

   128      */

   129     virtual void ReWakeAutomaticConnectionModeL() = 0;

   130 

   131 

   132 

   133 public: //New connection open related methods

   134 

   135     /**

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

   137      *

   138      * Called just before opening the network connection.

   139      * (aSapConnectionOpen is reported as EFalse)

   140      *

   141      * Or if the network connection is already open,

   142      * called before issuing the client asynchronous

   143      * processing (now the aSapConnectionOpen is ETrue)

   144      *

   145      * NOTE!! This initialization request might

   146      * come several times during one login try

   147      * depending the Presence Engine behaviour.

   148      *

   149      * @since 2.1

   150      * @param aSapConnectionOpen ETrue if the SAP connection is

   151      * already open. Else EFalse.

   152      * @param aSap The SAP settings details.

   153      */

   154     virtual void ConnectionOpenInitL( TBool aSapConnectionOpen,

   155                                       const CIMPSSAPSettings& aSap ) = 0;

   156 

   157 

   158     /**

   159      * Called to determine has the network server enough

   160      * capabilities for client type. This method is called

   161      * after the network connection to SAP

   162      * is succesfully opened.

   163      *

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

   165      * have enough capabilities), login procedure is immediately

   166      * stopped to insufficient capabilities error, and no

   167      * further plug-in processing methods is called.

   168      *

   169      * @since 2.1

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

   171      * has enough capabilities for this client type.

   172      * Else EFalse.

   173      */

   174     virtual TBool VerifySapCapabilitiesL() = 0;

   175 

   176 

   177     /**

   178      * Issues the plug-in to do asynchronous processing

   179      * related to connection open. This is issued after

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

   181      * enough capabilities.

   182      *

   183      * Plug-in has to initialize the given request status

   184      * to KRequestPending state if it starts the asynchronous

   185      * processing.

   186      *

   187      * If Plug-in leaves from starting the asynchronous

   188      * processing, it is considered to mean that starting the

   189      * asynchronous operation failed and there isn't any

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

   191      * between real operation start and method call return.)

   192      *

   193      * @since 2.1

   194      * @param aStatus The request status to complete when

   195      * asynchronous processing is done. Needs to be

   196      * initialized to KRequestPending state when

   197      * asynchronous processing is started.

   198      */

   199     virtual void DoPostLoginProsessingL( TRequestStatus& aStatus ) = 0;

   200 

   201 

   202     /**

   203      * This method must cancels the previously started

   204      * post login asynchronous processing.

   205      *

   206      * NOTE!! This method implementation must be such that

   207      * it copes from canceling not started operations /

   208      * partly constructed object.

   209      *

   210      * @since 2.1

   211      */

   212     virtual void CancelPostLoginProsessing() = 0;

   213 

   214 

   215 public: //New connection close related methods

   216 

   217 

   218     /**

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

   220      *

   221      * Called just before issuing the plug-in to do

   222      * its pre logout processing.

   223      *

   224      * @since 2.1

   225      * @param aSap The SAP settings details.

   226      */

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

   228 

   229 

   230     /**

   231      * Issues the plug-in to do asynchronous processing

   232      * related to connection close. This processing takes

   233      * place before closing that actual network connection.

   234      *

   235      * Plug-in has to initialize the given request status

   236      * to KRequestPending state if it starts the asynchronous

   237      * processing.

   238      *

   239      * If Plug-in leaves from starting the asynchronous

   240      * processing, it is considered to mean that starting the

   241      * asynchronous operation failed and there isn't any

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

   243      * between real operation start and method call return.)

   244      *

   245      * @since 2.1

   246      * @param aStatus The request status to complete when

   247      * asynchronous processing is done. Needs to be

   248      * initialized to KRequestPending state when

   249      * asynchronous processing is started.

   250      */

   251     virtual void DoPreLogoutProsessingL( TRequestStatus& aStatus ) = 0;

   252 

   253 

   254     /**

   255      * This method must cancels the previously started

   256      * pre logout asynchronous processing.

   257      *

   258      * NOTE!! This method implementation must be such that

   259      * it copes from canceling not started operations /

   260      * partly constructed object.

   261      *

   262      * @since 2.1

   263      */

   264     virtual void CancelPreLogoutProsessing() = 0;

   265 

   266     /**

   267      * From MCnUiClientPlugin

   268      * Publishes commcap attribute closed

   269      * @see MCnUiClientPlugin

   270      * @since 2.1

   271      */

   272     virtual void LoginCancelledL() = 0;

   273 

   274 public: //Destructor

   275 

   276     /**

   277      * Virtual destructor.

   278      *

   279      * Allows destruction using

   280      * this interface.

   281      */

   282     virtual ~MCnUiClientPlugin() {};

   283     };

   284 

   285 

   286 

   287 #endif      //  __MCNUICLIENTPLUGIN_H

   288 

   289 //  End of File

   290