diff -r 6ca72c0fe49a -r a941bc465d9f inc/CPEngPresenceNotifier2.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/inc/CPEngPresenceNotifier2.h Wed Sep 01 12:31:13 2010 +0100 @@ -0,0 +1,403 @@ +/* +* Copyright (c) 2004 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: Notifier API to listen presence changes. +* +*/ + +#ifndef __CPENGPRESENCENOTIFIER2_H +#define __CPENGPRESENCENOTIFIER2_H + +// INCLUDES +#include +#include +#include + + + + +//FORWARD DECLARATIONS +class MPEngPresenceObserver2; +class CPEngTrackedPresenceIDs2; +class CPEngPresenceNotifier2Imp; +class CPEngNWSessionSlotID2; + + + + +/** + * Notifier API for presence changes. + * + * With this API clients can + * 1. Receive notifications from changes in cached + * presence attributes. Cached presence attributes + * are subscribed or fetched presence attributes + * stored to presence cache. + * + * Notifications are triggered from: + * - Attribute creation to presence cache when + * the user is subscribed + * + * - Attribute value changes in presence cache + * after receiving attribute notification from network + * or attributes were manually fetched from network + * + * - Attribute removal from storage when user + * attributes are unsubscribed or fetched + * attributes are cleared. + * + * Thus, client can request presence notifications from + * such Presence IDs and presence attributes that do not + * exist yet in presence cache. Clients must be prepared + * also to handle the cases that attribute doesn't anymore + * exist in storage, if the notification was delivered due + * attribute clearing from storage. + * + * 2. Receive notifications from user own attribute changes. + * Notification from user own attributes is requested with + * zero length PresenceID and they are also delivered with + * zero length PresenceID. (See: KPEngUserOwnPresenceId from + * PEngPresenceEngineConsts2.h) + * + * @lib PEngManager2.lib + * @since 3.0 + */ +class CPEngPresenceNotifier2 : public CBase + { + //----------------------------------------------------------------------- + public: /* Construction */ + + /** + * Instantiates CPEngPresenceNotifier2 object. + * + * Instantiates CPEngPresenceNotifier2 object and connects it to + * identified Presence Engine side NWSessionSlot. NWSessionSlot + * must be a valid, existing slot. + * + * Errors: + * - Requested NWSessionSlot not found: KErrNotFound + * - Given NWSessionSlotID malformed: KErrArgument + * + * @param aNWSessionSlotID The session slot ID to identify the + * session slot. + * @param aPriority The priority for CPEngPresenceNotifier2 + * client side active objects. These active objects are used when + * asynchronously delivering events to observers. + * + * @return New CPEngPresenceNotifier2 instance. + */ + IMPORT_C static CPEngPresenceNotifier2* NewL( + const CPEngNWSessionSlotID2& aNWSessionSlotID, + TInt aPriority = CActive::EPriorityStandard ); + + IMPORT_C static CPEngPresenceNotifier2* NewLC( + const CPEngNWSessionSlotID2& aNWSessionSlotID, + TInt aPriority = CActive::EPriorityStandard ); + + + /** + * Destructor. + * Virtual by CBase. + */ + ~CPEngPresenceNotifier2(); + + + + protected: + + /** + * C++ constructor. + */ + CPEngPresenceNotifier2(); + + + + //----------------------------------------------------------------------- + public: /* Basic Presence notifier */ + + /** + * Check if the notifier is active. + * + * @since 3.0 + * @return ETrue if the notifier is active. Else EFalse. + */ + IMPORT_C TBool IsActive() const; + + + /** + * Starts observing presence changes. + * Ignores duplicate presence attributes. + * + * @since 3.0 + * @param aPresenceID Presence ID which changes to track. + * @param aTypes The attribute types to track. Attribute types + * known by Presence Engine are listed in + * PEngWVPresenceAttributes2.h. + * + * @return Result from observer start. + * - KErrNone if notifier start succeeds. + * - KErrNotSupported if attribute type isn't supported. + * - KErrInUse if notifier already started. + * - Else one of system wide error codes. + */ + IMPORT_C TInt Start( const TDesC& aPresenceID, + const TArray& aTypes ); + + + /** + * Starts observing presence changes. + * Ignores duplicate presence attributes and presence IDs. + * Presence ID list can be empty. + * + * @since 3.0 + * @param aPresenceIDs Presence IDs which changes to track. + * @param aTypes The attribute types to track. Attribute types + * known by Presence Engine are listed in + * PEngWVPresenceAttributes2.h. + * + * @return Result from observer start. + * - KErrNone if notifier start succeeds. + * - KErrNotSupported if attribute type isn't supported. + * - KErrInUse if notifier already started. + * - Else one of system wide error codes. + */ + IMPORT_C TInt Start( const MDesCArray& aPresenceIDs, + const TArray& aTypes ); + + + /** + * Starts observing presence changes. + * Ignores duplicate presence attributes and presence IDs. + * Presence ID list can be empty. + * + * @since 3.0 + * @param aList The contact list from which to take + * tracked Presence IDs. + * @param aContactListView From which contact list + * view to take observed contacts. + * @param aTypes The attribute types to track. Attribute types + * known by Presence Engine are listed in + * PEngWVPresenceAttributes2.h. + * + * @return Result from observer start. + * - KErrNone if notifier start succeeds. + * - KErrNotSupported if attribute type isn't supported. + * - KErrInUse if notifier already started. + * - Else one of system wide error codes. + */ + IMPORT_C TInt Start( const MPEngContactList2& aList, + TPEngContactListView aContactListView, + const TArray& aTypes ); + + + /** + * Stops observing presence changes. + * + * @since 3.0 + */ + IMPORT_C void Stop(); + + + + //----------------------------------------------------------------------- + public: /* Track list update */ + + /** + * Updates the list of observed presence IDs. Replaces + * list of tracked Presence ID's with given list. + * (Same effect than using separated Stop() and Start() calls + * but is much more efficient.) Uses presence attributes given + * in CPEngPresenceNotifier2::Start(). Ignores duplicate + * presence IDs. + * + * @since 3.0 + * @param aPresenceIDs List of Presence IDs which changes to track. + * + * @return Result from observer start. + * - KErrNone if notifier update succeeds. + * - KErrNotReady if notifier not started. + * - Else one of system wide error codes. + */ + IMPORT_C TInt Update( const MDesCArray& aPresenceIDs ); + + + + /** + * Updates the list of observed presence IDs. Replaces + * list of tracked Presence ID's with given list. + * (Same effect than using separated Stop() and Start() calls + * but is much more efficient.) Uses presence attributes given + * in CPEngPresenceNotifier2::Start(). Ignores duplicate + * presence IDs. + * + * @since 3.0 + * @param aList The contact list from which to take + * tracked Presence IDs. + * @param aContactListView From which contact list + * view to take observed contacts. + * + * @return Result from observer start. + * - KErrNone if notifier update succeeds. + * - KErrNotReady if notifier not started. + * - Else one of system wide error codes. + */ + IMPORT_C TInt Update( const MPEngContactList2& aList, + TPEngContactListView aContactListView ); + + + + + //----------------------------------------------------------------------- + public: /* Presence ID and attribute handling */ + + + + + /** + * Adds Presence ID to the list of tracked presences. + * + * @since 3.0 + * @param aPresenceID Presence ID which changes to track. + * If Presence ID is already tracked, new requested + * attributes are added in the list of tracked attributes. + * @param aTypes The attribute types to track. Attribute types + * known by Presence Engine are listed in + * PEngWVPresenceAttributes2.h. Ignores duplicate + * presence attributes. + * + * @return Result from adding Presence ID. + * - KErrNone if Presence ID add succeeds. + * - KErrNotSupported if attribute type isn't supported. + * - KErrNotReady if notifier not started. + * - Else one of system wide error codes. + */ + IMPORT_C TInt Add( const TDesC& aPresenceID, + const TArray& aTypes ); + + + /** + * Removes Presence ID from the list of tracked presences. + * + * @since 3.0 + * @param aPresenceID Presence ID which tracking to stop. + * + * @return Result from removing Presence ID. + * - KErrNone if Presence ID remove succeeds. + * - KErrNotReady if notifier not started. + * - KErrNotFound if Presence ID not tracked. + * - Else one of system wide error codes. + */ + IMPORT_C TInt Remove( const TDesC& aPresenceID ); + + + + + /** + * Removes Presence attribute from the list of tracked + * attributes. Removes also such Presence IDs from + * the tracked ones which do not have anymore tracked + * attributes. + * + * @since 3.0 + * @param aType Attribute type which tracking to stop. Attribute + * types known by Presence Engine are listed in + * PEngWVPresenceAttributes2.h. + * + * @return Result from removing attribute. + * - KErrNone if attribute remove succeeds. + * - KErrNotSupported if attribute type isn't supported. + * - KErrNotReady if notifier not started. + * - KErrNotFound if attribute not tracked. + * - Else one of system wide error codes. + */ + IMPORT_C TInt Remove( TUint32 aType ); + + + + + //----------------------------------------------------------------------- + public: /* Tracked presence IDs */ + + + /** + * Tracked Presence ID's. + * + * Gets the list of tracked Presence ID's. + * Tracked Presence IDs can be iterated with: + * - CPEngTrackedPresenceIDs2::FirstTrackedPresenceID() + * - CPEngTrackedPresenceIDs2::NextTrackedPresenceID() + * + * List holds also information from last notified + * changes. (Thus clients can access the notify information + * also after notify callback has gone, without making a + * copy from data. However, each new notification + * overwrites the data from previous notification.) + * + * Last changed Presence ID's can be iterated with: + * - CPEngTrackedPresenceIDs::FirstChangedPresenceID() + * - CPEngTrackedPresenceIDs::NextChangedPresenceID() + * + * @since 3.0 + * @return Collection of tracked Presence ID's. + */ + IMPORT_C const CPEngTrackedPresenceIDs2& TrackedPresenceIDs() const; + IMPORT_C CPEngTrackedPresenceIDs2& TrackedPresenceIDs(); + + + + + //----------------------------------------------------------------------- + public: /* Presence observers */ + + + /** + * Registers observer to be notified from presence changes. + * + * Observers are notified in their registeration order. + * (First registerd notified first.) + * + * @param aObserver The observer to be notified. + * Panics if NULL pointer passed. + * @return KErrNone is observer added succesfully. + * Else one of the system wide error codes. + */ + IMPORT_C TInt AddObserver( + MPEngPresenceObserver2& aObserver ); + + + + /** + * Unregisters presence observer. + * + * @param aObserver The observer to remove. + * @return KErrNone is observer removed succesfully. + * KErrNotFound if the observer wasn't registered. + */ + IMPORT_C TInt RemoveObserver( + MPEngPresenceObserver2& aObserver ); + + + + //----------------------------------------------------------------------- + private: /* Data */ + + + //OWN: Implementation + CPEngPresenceNotifier2Imp* iImp; + + + }; + +#endif //__CPENGPRESENCENOTIFIER2_H + +// End of File