--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/wvuing/wvuipresence/inc/MCAPresence.h Thu Dec 17 08:41:52 2009 +0200
@@ -0,0 +1,351 @@
+/*
+* Copyright (c) 2002 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: Presence handling interface for clients.
+*
+*/
+
+
+#ifndef MCAPRESENCE_H
+#define MCAPRESENCE_H
+
+// INCLUDES
+#include <e32std.h>
+#include <badesca.h>
+#include "impsbuilddefinitions.h"
+
+// FORWARD DECLARATIONS
+class MCAPresenceObserver;
+class MCAWatcherObserver;
+class MCAContactLists;
+class CCAPresenceErrors;
+class CPEngNWSessionSlotID2;
+class MCAStoredContact;
+class MCAReactiveAuthObserver;
+
+struct SServerPrefers;
+
+// CLASS DECLARATION
+
+/**
+* Presence handling interface for UI.
+*
+* @lib CAPresence.lib
+* @since 1.2
+*/
+class MCAPresence
+ {
+ public:
+
+ enum TSubscribeMode
+ {
+ ESubscribe, // Subscribe
+ EUnSubscribe // Unsubscribe
+ };
+
+ enum TAuthorizationMode
+ {
+ EAuthorizedToAll, // Everybody can see your presence
+ EAuthorizedToFriends, // Only friends can see your presence
+ EAuthorizedToNone // Nobody can see your presence
+ };
+
+ enum TNetworkStatus
+ {
+ ELoggedIn, // Client is logged in
+ ELoggedOut, // Client is logged out
+ ELoggingOut, // Client is about to log out
+ EUpdateBrand // Brand status of client is changed
+ };
+
+ enum TPresenceStatus
+ {
+ EUnknown = -1,
+ EOffline,
+ EOnline,
+ EAway,
+ EBusy
+ };
+
+ enum TDynamicAttributes
+ {
+ EAliasAttr = 0
+ // add more here
+ };
+
+ public:
+
+ /**
+ * If network state changes, module state should be updated by calling
+ * this method.
+ * @param aState New state.
+ * @param aServerPreferences Server preferences structure
+ */
+ virtual void HandleNetworkStateL( TNetworkStatus aState,
+ const SServerPrefers& aServerPreferences,
+ CPEngNWSessionSlotID2* aSessionSlotID = NULL ) = 0;
+
+ /**
+ * If some setting value changes, this must be called for presence
+ * module to have correct behaviour
+ * @param aState New state.
+ */
+ virtual void HandleSettingsChangeL( TInt aChangedSettingEnum ) = 0;
+
+ /**
+ * Registers observer for presence data changes in friends-list.
+ * Unregister can be by passing NULL pointer.
+ * @param aObserver Pointer to observer
+ */
+ virtual void SetPresenceObserver( MCAPresenceObserver* aObserver ) = 0;
+
+ /**
+ * Retrieves the observer.
+ * @return Pointer to the observer.
+ */
+ virtual MCAPresenceObserver* PresenceObserver() const = 0;
+
+ /**
+ * Registers observer for presence data changes in friends-list.
+ * Unregister can be by passing NULL pointer.
+ * @param aObserver Pointer to observer.
+ */
+ virtual void SetWatcherObserver( MCAWatcherObserver* aObserver ) = 0;
+
+ /**
+ * Adds a contact, whose presence status is monitored and if
+ * it changes, then client receives an event through.
+ * MCAWatcherObserver-interface. Given contact must be in friends-list!
+ * @param aWatchList Contact, that gets added.
+ */
+ virtual void AddWatcherL( const TDesC& aWVId ) = 0;
+
+ /**
+ * Removes a contact from observed contacts list.
+ * Given contact must be in observed list.
+ * @param aWatchList Contact, that is to be removed.
+ */
+ virtual void RemoveWatcherL( const TDesC& aWVId ) = 0;
+
+ /**
+ * Refreshes friends-storage presence data.
+ */
+ virtual void RefreshFriendsL() = 0;
+
+ /**
+ * Places all friends (from aUserList) that are online to aOnlineList
+ * and users that are offline to aOfflineList.
+ * @param aUserList List of users, whose presence data is to be fetched.
+ * @param aOnlineList List of users, that are online, can be NULL.
+ * @param aOfflineList List of users, that are offline, can be NULL.
+ * @param aUpdateStorage If ETrue, contact storage flags are updated
+ */
+ virtual void GetOnlineUsersL(
+ const CDesCArray& aUserList,
+ CDesCArray* aOnlineList,
+ CDesCArray* aOfflineList,
+ TBool aUpdateStorage = EFalse ) = 0;
+
+ /**
+ * Fills aOnlineList with the user id's from friends-list that are
+ * online.
+ * @param aOnlineList List that will be populated with online friends.
+ * @param aFetchFromNetwork Fetch presence information from network
+ */
+ virtual void GetOnlineFriendsL( CDesCArray& aOnlineList,
+ TBool aFetchFromNetwork = EFalse ) = 0;
+
+ /**
+ * Subscribes/Unsubscribes friends-list
+ * @param aMode Request type
+ * @param aForced Force operation even if application settings state
+ * that application is in manual-mode
+ */
+ virtual void SubscribeFriendsL( const TSubscribeMode aMode ) = 0;
+
+ /**
+ * Returns list-handling interface
+ * @return List-handling interface
+ */
+ virtual MCAContactLists* ContactLists() = 0;
+
+ /**
+ * Returns a reference to error container, that was filled by the last
+ * operation response.
+ * @return Reference to error container
+ */
+ virtual const CCAPresenceErrors& LastOperationResult() const = 0;
+
+ /**
+ * Cancel pending requests to network
+ * @since 2.5
+ */
+ virtual void CancelPendingRequests() = 0;
+
+ /**
+ * Synchronizes our presence-related settings to the server
+ * (subcriptions to the friends, presence authorization).
+ * aServerPreferences The resource branded flags for this server,
+ in a struct
+ * @since 2.5
+ */
+ virtual void SynchronizePresenceSettingsL(
+ const SServerPrefers& aServerPreferences ) = 0;
+
+ /**
+ * Changes client own presence status, and sets status message
+ * @param aStatus Presence status
+ * @param aStatusMessage Presence status message
+ * @return Error code.
+ */
+ virtual TInt ChangeStatusL( TPresenceStatus aStatus,
+ const TDesC& aStatusMessage ) = 0;
+
+ /**
+ * Changes presence status message
+ * @param aStatusMessage Presence status message
+ * @return Operation error.
+ */
+ virtual TInt ChangeStatusMessageL( const TDesC& aStatusMessage ) = 0;
+
+ /**
+ * Gets client own current presence status
+ * @return current presence status
+ */
+ virtual TPresenceStatus StatusL() = 0;
+ /**
+ * Get alias for given user.
+ * Use this only for one-shot rare operations.
+ * @param aUserId The user id for which to fetch alias attribute
+ * @return The alias, ownership is transferred.
+ * Leaves with KErrNotFound if the alias cannot be found,
+ * otherwise some other KErr-code (e.g. KErrNoMemory)
+ */
+ virtual HBufC* AliasL( const TDesC& aUserId ) = 0;
+
+ /**
+ * Get alias for given user.
+ * Use this only for one-shot rare operations.
+ * @param aContact The user for which to fetch alias attribute
+ * @return The alias, ownership is transferred.
+ * Leaves with KErrNotFound if the alias cannot be found,
+ * otherwise some other KErr-code (e.g. KErrNoMemory)
+ */
+ virtual HBufC* AliasL( MCAStoredContact* aContact ) = 0;
+
+ /**
+ * Adds own presence status observer.
+ * Leaves with KErrNotReady if not logged in.
+ */
+ virtual void AddOwnPresenceStatusObserverL(
+ MCAPresenceObserver* aObserver ) = 0;
+
+ /**
+ * Initializes presence engine interface
+ */
+ virtual void InitializePresenceAPIL(
+ CPEngNWSessionSlotID2& aSessionSlotID ) = 0;
+
+ /**
+ * Add given attribute to the list of attributes.
+ * After this the new attributesd will be
+ * subscribed to.
+ * @param aAttribute The attribute to add
+ */
+ virtual void AddAttributeL( TInt aAttribute ) = 0;
+
+ /**
+ * Remove given attribute from the list of attributes
+ * After this the new attributesd will be
+ * subscribed to.
+ * @param aAttribute The attribute to remove
+ */
+ virtual void RemoveAttributeL( TInt aAttribute ) = 0;
+
+ /**
+ * Reset the attributes to defaults.
+ * @param aNotifyListManager Notify the list manager about the
+ * resetting (ETrue), or not (EFalse)
+ */
+ virtual void ResetAttributesL( TBool aNotifyListManager = ETrue ) = 0;
+
+ /**
+ * Update the alias data to network server, if supported
+ */
+ virtual void UpdateAliasAttributeL() = 0;
+
+ /**
+ * Set the observer for reactive authorization
+ */
+ virtual void SetReactiveAuthObserver(
+ MCAReactiveAuthObserver* aRAObserver ) = 0;
+
+ /**
+ * Send reactive authorization response
+ * @param aId The id number given through observer
+ * @param aResponse The response, ETrue if authorizing,
+ EFalse if denying
+ */
+ virtual void SendReactiveAuthResponseL( TInt aId, TBool aResponse ) = 0;
+
+ /**
+ * @return The number of pending requests
+ */
+ virtual TInt PendingRARequestCount() = 0;
+
+ /**
+ * Get the information from the next reactive authorization request for
+ * processing
+ * @param aId Will contain the id for the request
+ * @param aUserId Will contain the user id
+ * @param aLastPos Position of previous found request in queue
+ * @return ETrue if there is another request in the queue
+ */
+ virtual TBool GetNextPendingRARequestL( TInt& aId, TDes& aUserId,
+ TInt& aLastPos ) = 0;
+
+ /**
+ * @return The number of new status messages
+ */
+ virtual TInt RAStatusCount() = 0;
+
+ /**
+ * Get the information from the next reactive authorization status
+ * request for processing
+ * @param aId Will contain the id for the request
+ * @param aStatus ETrue if accepted, EFalse if denied
+ * @param aUserId Will contain the user id
+ * @param aLastPos Position of previous found request in queue
+ * @return ETrue if there is another request in the queue
+ */
+ virtual TBool GetNextRAStatusL( TInt& aId, TBool& aStatus,
+ TDes& aUserId, TInt& aLastPos ) = 0;
+
+ /**
+ * Called after the login is fully done, this method will notify the
+ * observers of any RA messages received during the login phase.
+ */
+ virtual void PostLoginRAFlushL() = 0;
+
+ protected:
+
+ /**
+ * Destructor.
+ */
+ virtual ~MCAPresence() {};
+ };
+
+#endif // MCAPRESENCE_H
+
+// End of File
+