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