/*

* 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