/*
* 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