MCL/sf/app/im: comparison inc/CPEngPresenceNotifier2.h

equal deleted inserted replaced

--1:000000000000
+:094583676ce7
+/*
+* 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