1 /*

     2 * Copyright (c) 2005 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:  IMPS Connection UI.

    15 *

    16 */

    17 

    18 #ifndef __CIMPSPRESENCECONNECTIONUING_H__

    19 #define __CIMPSPRESENCECONNECTIONUING_H__

    20 

    21 // INCLUDES

    22 #include <E32base.h>

    23 #include <PEngPresenceEngineConsts2.h>

    24 #include <impspresenceconnectionuiconstsng.h>

    25 

    26 

    27 

    28 // FORWARD DECLARATION

    29 class MIMPSConnProcessObserver;

    30 class CIMPSSAPSettingsStore;

    31 class CIMPSPresenceConnectionUiImp;

    32 class CIMPSSAPSettings;

    33 class CPEngNWSessionSlotID2;

    34 

    35 // CLASS DECLARATION

    36 /**

    37  * CIMPSPresenceConnectionUi.

    38  *

    39  * CIMPSPresenceConnectionUi encapsulates remote Presence Server connection /

    40  * disconnection procedures. CIMPSPresenceConnectionUi allows applications

    41  * just execute the connection procedure, CIMPSPresenceConnectionUi shows

    42  * all required UI notes, asks login data from user when needed, etc.

    43  *

    44  * @lib IMPSConnectionUi

    45  * @since 3.0

    46  */

    47 class CIMPSPresenceConnectionUi : public CBase

    48     {

    49     public:  // Two-phased constructors and destructor

    50 

    51         /**

    52          * Two-phased constructor.

    53          *

    54          * @param aClient The client using the Connection UI

    55          * @param aSapStore The SAP settings store to use.

    56          * Given SAP settings store object lifetime must be

    57          * longer than created CIMPSPresenceConnectionUi.

    58          * If no SAP settings store provided, creates own

    59          * SAP Settings store internally when needed.

    60          */

    61         IMPORT_C static CIMPSPresenceConnectionUi* NewL(

    62             TIMPSConnectionClient aClient,

    63             CIMPSSAPSettingsStore* aSapStore = NULL );

    64 

    65         /**

    66          * Two-phased constructor.

    67          * Leaves CIMPSPresenceConnectionUi object on the

    68          * CleanupStack.

    69          *

    70          * @param aClient The client using the Connection UI

    71          * @param aSapStore The SAP settings store to use.

    72          * Given SAP settings store object lifetime must be

    73          * longer than created CIMPSPresenceConnectionUi.

    74          * If no SAP settings store provided, creates own

    75          * SAP Settings store internally when needed.

    76          */

    77         IMPORT_C static CIMPSPresenceConnectionUi* NewLC(

    78             TIMPSConnectionClient aClient,

    79             CIMPSSAPSettingsStore* aSapStore = NULL );

    80 

    81 

    82         /**

    83          * Destructor.

    84          */

    85         IMPORT_C virtual ~CIMPSPresenceConnectionUi();

    86 

    87 

    88     public:  // New connection handling methods

    89 

    90 

    91         /**

    92          * Connects to remote presence server.

    93          *

    94          * Handles error situations internally by showing

    95          * a proper error note. Asks login data and used server

    96          * from user when needed. Retries to open the connection if

    97          * needed.

    98          *

    99          * Connection status is returned as return value.

   100          * Internal Symbian OS errors (like running out of resources,

   101          * or other fatal errors coming from underlying Presence Engine)

   102          * are handled by leaving.

   103          *

   104          * The client must intialize an instance of CPEngNWSessionSlotID2

   105          * and give it as a parameter. When the call returns the slot ID

   106          * contains the current active connection's network session slot ID.

   107          *

   108          * @since 3.0

   109          * @param aClient The client using the Connection UI to login

   110          * to presence service. (This client is logged in.)

   111          * @param aLoginType Wanted Connection UI behaviour.

   112          * @param aNWSessionSlotID a network session slot ID, on return will contain

   113          *        the active network session slot ID

   114          * @param aObserver The observer to notify from login process

   115          * events.

   116          * @return Login operation status, one of following:

   117          * - KErrNone ==> Login succeeded

   118          * - KErrNotFound ==> Missing the whole default SAP / or no SAP's at all

   119          * - KErrArgument ==> Default / selected SAP to login was

   120          *                    missing some required fields. (URL & AccessPoint)

   121          * - KErrCancel ==> User has cancelled the login at some point.

   122          * - KErrAlreadyExist ==> Current client is already logged in.

   123          *                        (Thus not a real error.)

   124          * - KErrGeneral ==> General failure during login (no connection

   125          *                   to network, network access denied, etc..)

   126          */

   127         IMPORT_C TInt LoginL( TIMPSConnectionClient aClient,

   128                               TIMPSLoginType aLoginType,

   129                               CPEngNWSessionSlotID2& aNWSessionSlotID,

   130                               MIMPSConnProcessObserver* aObserver = NULL,

   131                               CIMPSSAPSettings* aSap = NULL, TBool aLastLoginSap = EFalse );

   132 

   133 

   134         /**

   135          * Disconnects from remote presence server.

   136          *

   137          * Internal Symbian OS errors (like running out of resources,

   138          * or other fatal errors coming from underlying Presence Engine)

   139          * are handled by leaving.

   140          *

   141          * @since 3.0

   142          * @param aNWSessionSlotID a network session slot ID to logout from.

   143          * @param aObserver The observer to notify from logout process

   144          * events.

   145          * @return Currently always KErrNone.

   146          */

   147         IMPORT_C TInt LogoutL( const CPEngNWSessionSlotID2& aNWSessionSlotID,

   148                                MIMPSConnProcessObserver* aObserver = NULL );

   149 

   150 

   151         /**

   152          * Handles the application exit according the

   153          * IMPS Server Settings specification.

   154          *

   155          * Internal Symbian OS errors (like running out of resources,

   156          * or other fatal errors coming from underlying Presence Engine)

   157          * are handled by leaving.

   158          *

   159          * @since 3.0

   160          * @param aClient Which client categorys exit to handle.

   161          *

   162          * @param TIMPSExitType Wished  behaviour of handle exit.

   163          * EIMPSNormalExit:

   164          * If there exist open connection for the given application

   165          * category, and the connection type is is  manual or application

   166          * launch, a confirmation query is opened wether to close

   167          * open connection or not. Connection is closed if desired so.

   168          * EIMPSForceExit:

   169          * No confirmation queries etc. isn't shown.

   170          * Existing open connection is silently closed.

   171          *

   172          * EIMPSLeaveSessionOpenExit:

   173          * The network session is left open by storing the network session

   174          * slot ownership to Presence engine. This ownership is restored

   175          * next time the application starts

   176          *

   177          * @param aNWSessionSlotID the current network session slot ID.

   178          * @param aObserver The observer to notify from logout process

   179          * events.

   180          * @return Currently always KErrNone.

   181          */

   182         IMPORT_C TInt HandleApplicationExitL( TIMPSConnectionClient aClient,

   183                                               TIMPSExitType aExitType,

   184                                               const CPEngNWSessionSlotID2& aNWSessionSlotID,

   185                                               MIMPSConnProcessObserver* aObserver = NULL );

   186 

   187         /**

   188          * Gets the remote presence server connection status.

   189          *

   190          * @since 3.0

   191          * @param aClient The client which connection status

   192          * to check.

   193          * @return ETrue if client is logged in, else EFalse.

   194          */

   195         IMPORT_C TBool LoggedInL( TIMPSConnectionClient aClient );

   196 

   197         /**

   198          * Gets the currently active network session slot id.

   199          * If there is no active network session slot ID return

   200          * the default SAP's network session slot ID.

   201          * If there are no SAPs defined in the system leaves

   202          * with KErrNotFound.

   203          * Note that ownership is transferred to the caller.

   204          *

   205          * @since 3.0

   206          * @param aClient The client which slots to get

   207          * @return the network session slot ID

   208          */

   209         IMPORT_C CPEngNWSessionSlotID2* GetActiveNWSessionSlotIDL( TIMPSConnectionClient aClient );

   210 

   211 

   212         /**

   213          * Gets the remote presence server settings.

   214          *

   215          * Gets the remote presence server settings for

   216          * current connection. There can be just one

   217          * real network presence connection active at time,

   218          * and this method retrieves details of that

   219          * connection. (Different client groups share

   220          * logically on real network connection.)

   221          *

   222          * If there isn't a active (logged in) connection

   223          * for any of known clients, returns KErrNotFound.

   224          * Else the given aSap is filled with connection

   225          * settings and KErrNone is returned.

   226          *

   227          * If sap get fails due out of resources or to some

   228          * other fatal error coming from underlying PEC engine,

   229          * leaves with system error codes. In this case

   230          * aSap parameter state is undetermined.

   231          *

   232          * @since 3.0

   233          * @param aNWSessionSlotID the current active network session slot ID

   234          * @param aSap The SAP container to fill with current

   235          * connection settings.

   236          * @return KErrNone if there exist a connection for known

   237          * client. Else KErrNotFound.

   238          */

   239         IMPORT_C TInt GetLoggedInSapL( const CPEngNWSessionSlotID2& aNWSessionSlotID,

   240                                        CIMPSSAPSettings& aSap );

   241 

   242 

   243 

   244         /**

   245          * Gets the pure connection status from Presence Engine.

   246          *

   247          * @since 3.0

   248          * @param aNWSessionSlotID a network session slot ID

   249          * @return Connection status from Presence Engine.

   250          */

   251         IMPORT_C TPEngNWSessionSlotState PureServiceStatusL(

   252             const CPEngNWSessionSlotID2& aNWSessionSlotID );

   253 

   254 

   255         /**

   256          * Gets the currently ongoing connection

   257          * state change operation. Returned operation

   258          * is client wide, so it doesn't care about which

   259          * client is doing the operation.

   260          *

   261          * @since 3.0

   262          * @param aAddtionalDesc The descriptor describing / related

   263          * to current connection operation. Method allocates a

   264          * buffer for descriptive descriptor if needed and returns

   265          * its to caller trough the HBufC*& aDetailDesc.

   266          * Ownership of the created buffer is returned to

   267          * caller. (NOTE! Only EIMPSConnOppClientLogin returns

   268          * descriptive text, currently connected server name.

   269          * Other operations return NULL.)

   270          * @return The Current connection operation.

   271          */

   272         IMPORT_C TIMPSConnectionOperation CurrentConnectionOperationL( HBufC*& aAddtionalDesc );

   273 

   274     public:  // Other new functions

   275 

   276         /**

   277          * Displays a list query for selecting a domain ("@domain.com" etc.)

   278          * @param aSelectedDomain Here is copied the domain user selected.

   279          * @param aSap Current SAP settings, previously selected domain is

   280          *             stored per SAP.

   281          * @return If user cancelled the query return 0,

   282          *         otherwise the dialog dismiss key code

   283          * @since 3.1u

   284          */

   285         IMPORT_C TInt DisplayDomainSelectionQueryL( TDes& aSelectedDomain,

   286                                                     CIMPSSAPSettings* aSap );

   287 

   288     private: //Constructors.

   289 

   290         /**

   291          * C++ default constructor.

   292          */

   293         CIMPSPresenceConnectionUi( TIMPSConnectionClient aClient );

   294 

   295 

   296         /**

   297          * Symbian OS constructor.

   298          */

   299         void ConstructL( CIMPSSAPSettingsStore* aSapStore );

   300 

   301 

   302     private: //Data

   303         CIMPSPresenceConnectionUiImp*     iImp;          ///<Implementation, owned

   304         TIMPSConnectionClient             iClient;       ///<Client using the Connection UI

   305         TAny*                             iReserved1;    ///<Reserved, owned

   306     };

   307 

   308 

   309 

   310 #endif      //__CIMPSPRESENCECONNECTIONUING_H__

   311 

   312 //  End of File

   313