--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/presadap12/Parser2/Inc/CPEngPresenceNotifier2.h Thu Dec 17 08:41:52 2009 +0200
@@ -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 <E32Base.h>
+#include <BamDesca.h>
+#include <MPEngContactList2.h>
+
+
+
+
+//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<TUint32>& 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<TUint32>& 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<TUint32>& 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<TUint32>& 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