--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/inc/cimpspresenceconnectionuing.h Thu Dec 17 08:41:52 2009 +0200
@@ -0,0 +1,313 @@
+/*
+* Copyright (c) 2005 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: IMPS Connection UI.
+*
+*/
+
+#ifndef __CIMPSPRESENCECONNECTIONUING_H__
+#define __CIMPSPRESENCECONNECTIONUING_H__
+
+// INCLUDES
+#include <E32base.h>
+#include <PEngPresenceEngineConsts2.h>
+#include <impspresenceconnectionuiconstsng.h>
+
+
+
+// FORWARD DECLARATION
+class MIMPSConnProcessObserver;
+class CIMPSSAPSettingsStore;
+class CIMPSPresenceConnectionUiImp;
+class CIMPSSAPSettings;
+class CPEngNWSessionSlotID2;
+
+// CLASS DECLARATION
+/**
+ * CIMPSPresenceConnectionUi.
+ *
+ * CIMPSPresenceConnectionUi encapsulates remote Presence Server connection /
+ * disconnection procedures. CIMPSPresenceConnectionUi allows applications
+ * just execute the connection procedure, CIMPSPresenceConnectionUi shows
+ * all required UI notes, asks login data from user when needed, etc.
+ *
+ * @lib IMPSConnectionUi
+ * @since 3.0
+ */
+class CIMPSPresenceConnectionUi : public CBase
+ {
+ public: // Two-phased constructors and destructor
+
+ /**
+ * Two-phased constructor.
+ *
+ * @param aClient The client using the Connection UI
+ * @param aSapStore The SAP settings store to use.
+ * Given SAP settings store object lifetime must be
+ * longer than created CIMPSPresenceConnectionUi.
+ * If no SAP settings store provided, creates own
+ * SAP Settings store internally when needed.
+ */
+ IMPORT_C static CIMPSPresenceConnectionUi* NewL(
+ TIMPSConnectionClient aClient,
+ CIMPSSAPSettingsStore* aSapStore = NULL );
+
+ /**
+ * Two-phased constructor.
+ * Leaves CIMPSPresenceConnectionUi object on the
+ * CleanupStack.
+ *
+ * @param aClient The client using the Connection UI
+ * @param aSapStore The SAP settings store to use.
+ * Given SAP settings store object lifetime must be
+ * longer than created CIMPSPresenceConnectionUi.
+ * If no SAP settings store provided, creates own
+ * SAP Settings store internally when needed.
+ */
+ IMPORT_C static CIMPSPresenceConnectionUi* NewLC(
+ TIMPSConnectionClient aClient,
+ CIMPSSAPSettingsStore* aSapStore = NULL );
+
+
+ /**
+ * Destructor.
+ */
+ IMPORT_C virtual ~CIMPSPresenceConnectionUi();
+
+
+ public: // New connection handling methods
+
+
+ /**
+ * Connects to remote presence server.
+ *
+ * Handles error situations internally by showing
+ * a proper error note. Asks login data and used server
+ * from user when needed. Retries to open the connection if
+ * needed.
+ *
+ * Connection status is returned as return value.
+ * Internal Symbian OS errors (like running out of resources,
+ * or other fatal errors coming from underlying Presence Engine)
+ * are handled by leaving.
+ *
+ * The client must intialize an instance of CPEngNWSessionSlotID2
+ * and give it as a parameter. When the call returns the slot ID
+ * contains the current active connection's network session slot ID.
+ *
+ * @since 3.0
+ * @param aClient The client using the Connection UI to login
+ * to presence service. (This client is logged in.)
+ * @param aLoginType Wanted Connection UI behaviour.
+ * @param aNWSessionSlotID a network session slot ID, on return will contain
+ * the active network session slot ID
+ * @param aObserver The observer to notify from login process
+ * events.
+ * @return Login operation status, one of following:
+ * - KErrNone ==> Login succeeded
+ * - KErrNotFound ==> Missing the whole default SAP / or no SAP's at all
+ * - KErrArgument ==> Default / selected SAP to login was
+ * missing some required fields. (URL & AccessPoint)
+ * - KErrCancel ==> User has cancelled the login at some point.
+ * - KErrAlreadyExist ==> Current client is already logged in.
+ * (Thus not a real error.)
+ * - KErrGeneral ==> General failure during login (no connection
+ * to network, network access denied, etc..)
+ */
+ IMPORT_C TInt LoginL( TIMPSConnectionClient aClient,
+ TIMPSLoginType aLoginType,
+ CPEngNWSessionSlotID2& aNWSessionSlotID,
+ MIMPSConnProcessObserver* aObserver = NULL,
+ CIMPSSAPSettings* aSap = NULL, TBool aLastLoginSap = EFalse );
+
+
+ /**
+ * Disconnects from remote presence server.
+ *
+ * Internal Symbian OS errors (like running out of resources,
+ * or other fatal errors coming from underlying Presence Engine)
+ * are handled by leaving.
+ *
+ * @since 3.0
+ * @param aNWSessionSlotID a network session slot ID to logout from.
+ * @param aObserver The observer to notify from logout process
+ * events.
+ * @return Currently always KErrNone.
+ */
+ IMPORT_C TInt LogoutL( const CPEngNWSessionSlotID2& aNWSessionSlotID,
+ MIMPSConnProcessObserver* aObserver = NULL );
+
+
+ /**
+ * Handles the application exit according the
+ * IMPS Server Settings specification.
+ *
+ * Internal Symbian OS errors (like running out of resources,
+ * or other fatal errors coming from underlying Presence Engine)
+ * are handled by leaving.
+ *
+ * @since 3.0
+ * @param aClient Which client categorys exit to handle.
+ *
+ * @param TIMPSExitType Wished behaviour of handle exit.
+ * EIMPSNormalExit:
+ * If there exist open connection for the given application
+ * category, and the connection type is is manual or application
+ * launch, a confirmation query is opened wether to close
+ * open connection or not. Connection is closed if desired so.
+ * EIMPSForceExit:
+ * No confirmation queries etc. isn't shown.
+ * Existing open connection is silently closed.
+ *
+ * EIMPSLeaveSessionOpenExit:
+ * The network session is left open by storing the network session
+ * slot ownership to Presence engine. This ownership is restored
+ * next time the application starts
+ *
+ * @param aNWSessionSlotID the current network session slot ID.
+ * @param aObserver The observer to notify from logout process
+ * events.
+ * @return Currently always KErrNone.
+ */
+ IMPORT_C TInt HandleApplicationExitL( TIMPSConnectionClient aClient,
+ TIMPSExitType aExitType,
+ const CPEngNWSessionSlotID2& aNWSessionSlotID,
+ MIMPSConnProcessObserver* aObserver = NULL );
+
+ /**
+ * Gets the remote presence server connection status.
+ *
+ * @since 3.0
+ * @param aClient The client which connection status
+ * to check.
+ * @return ETrue if client is logged in, else EFalse.
+ */
+ IMPORT_C TBool LoggedInL( TIMPSConnectionClient aClient );
+
+ /**
+ * Gets the currently active network session slot id.
+ * If there is no active network session slot ID return
+ * the default SAP's network session slot ID.
+ * If there are no SAPs defined in the system leaves
+ * with KErrNotFound.
+ * Note that ownership is transferred to the caller.
+ *
+ * @since 3.0
+ * @param aClient The client which slots to get
+ * @return the network session slot ID
+ */
+ IMPORT_C CPEngNWSessionSlotID2* GetActiveNWSessionSlotIDL( TIMPSConnectionClient aClient );
+
+
+ /**
+ * Gets the remote presence server settings.
+ *
+ * Gets the remote presence server settings for
+ * current connection. There can be just one
+ * real network presence connection active at time,
+ * and this method retrieves details of that
+ * connection. (Different client groups share
+ * logically on real network connection.)
+ *
+ * If there isn't a active (logged in) connection
+ * for any of known clients, returns KErrNotFound.
+ * Else the given aSap is filled with connection
+ * settings and KErrNone is returned.
+ *
+ * If sap get fails due out of resources or to some
+ * other fatal error coming from underlying PEC engine,
+ * leaves with system error codes. In this case
+ * aSap parameter state is undetermined.
+ *
+ * @since 3.0
+ * @param aNWSessionSlotID the current active network session slot ID
+ * @param aSap The SAP container to fill with current
+ * connection settings.
+ * @return KErrNone if there exist a connection for known
+ * client. Else KErrNotFound.
+ */
+ IMPORT_C TInt GetLoggedInSapL( const CPEngNWSessionSlotID2& aNWSessionSlotID,
+ CIMPSSAPSettings& aSap );
+
+
+
+ /**
+ * Gets the pure connection status from Presence Engine.
+ *
+ * @since 3.0
+ * @param aNWSessionSlotID a network session slot ID
+ * @return Connection status from Presence Engine.
+ */
+ IMPORT_C TPEngNWSessionSlotState PureServiceStatusL(
+ const CPEngNWSessionSlotID2& aNWSessionSlotID );
+
+
+ /**
+ * Gets the currently ongoing connection
+ * state change operation. Returned operation
+ * is client wide, so it doesn't care about which
+ * client is doing the operation.
+ *
+ * @since 3.0
+ * @param aAddtionalDesc The descriptor describing / related
+ * to current connection operation. Method allocates a
+ * buffer for descriptive descriptor if needed and returns
+ * its to caller trough the HBufC*& aDetailDesc.
+ * Ownership of the created buffer is returned to
+ * caller. (NOTE! Only EIMPSConnOppClientLogin returns
+ * descriptive text, currently connected server name.
+ * Other operations return NULL.)
+ * @return The Current connection operation.
+ */
+ IMPORT_C TIMPSConnectionOperation CurrentConnectionOperationL( HBufC*& aAddtionalDesc );
+
+ public: // Other new functions
+
+ /**
+ * Displays a list query for selecting a domain ("@domain.com" etc.)
+ * @param aSelectedDomain Here is copied the domain user selected.
+ * @param aSap Current SAP settings, previously selected domain is
+ * stored per SAP.
+ * @return If user cancelled the query return 0,
+ * otherwise the dialog dismiss key code
+ * @since 3.1u
+ */
+ IMPORT_C TInt DisplayDomainSelectionQueryL( TDes& aSelectedDomain,
+ CIMPSSAPSettings* aSap );
+
+ private: //Constructors.
+
+ /**
+ * C++ default constructor.
+ */
+ CIMPSPresenceConnectionUi( TIMPSConnectionClient aClient );
+
+
+ /**
+ * Symbian OS constructor.
+ */
+ void ConstructL( CIMPSSAPSettingsStore* aSapStore );
+
+
+ private: //Data
+ CIMPSPresenceConnectionUiImp* iImp; ///<Implementation, owned
+ TIMPSConnectionClient iClient; ///<Client using the Connection UI
+ TAny* iReserved1; ///<Reserved, owned
+ };
+
+
+
+#endif //__CIMPSPRESENCECONNECTIONUING_H__
+
+// End of File
+