/*
* 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 contact list changes.
*
*/

#ifndef __CPENGCONTACTLISTNOTIFIER2_H
#define __CPENGCONTACTLISTNOTIFIER2_H


//  INCLUDES
#include <E32Base.h>
#include <BamDescA.h>


//FORWARD DECLARATIONS
class MPEngContactListObserver2;
class MPEngContactList2;
class CPEngContactListNotifier2Imp;
class CPEngNWSessionSlotID2;



// CLASS DECLARATION

/**
 * Notifier API for presence contact list changes.
 *
 * With this API clients can
 * 1. Receive notifications from changes in presence
 *    contact lists contents (users added or removed).
 *
 * 2. Receive notifications from changes in presence
 *    contact lists settings.
 *
 * @lib PEngManager2.lib
 * @since 3.0
 */
class CPEngContactListNotifier2 : public CBase
    {
        //-----------------------------------------------------------------------
    public: /* Construction */

        /**
         * Instantiates CPEngContactListNotifier2 object.
         *
         * Instantiates CPEngContactListNotifier2 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 CPEngContactListNotifier2* NewL(
            const CPEngNWSessionSlotID2& aNWSessionSlotID,
            TInt aPriority = CActive::EPriorityStandard );

        IMPORT_C static CPEngContactListNotifier2* NewLC(
            const CPEngNWSessionSlotID2& aNWSessionSlotID,
            TInt aPriority = CActive::EPriorityStandard );


        /**
         * Destructor.
         * Virtual by CBase.
         */
        ~CPEngContactListNotifier2();



    protected:

        CPEngContactListNotifier2();




        //-----------------------------------------------------------------------
    public: /* Basic contact list 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 contact list changes.
         *
         * @since 3.0
         * @param aContactListName Contact list(s) which changes to track.
         * @return Result from observer start.
         * - KErrNone if notifier start succeeds.
         * - KErrInUse if notifier already started.
         * - KErrAlreadyExist if duplicate contact lists given.
         * - Else one of system wide error codes.
         */
        IMPORT_C TInt Start( const TDesC& aContactListName );
        IMPORT_C TInt Start( const MDesCArray& aContactListNames );


        /**
         * Stops observing contact list changes.
         *
         * @since 3.0
         */
        IMPORT_C void Stop();





        //-----------------------------------------------------------------------
    public: /* Advanced notifier features */


        /**
         * Adds contact list to the list of tracked contact lists.
         *
         * @since 3.0
         * @param aContactListName Contact list which changes to track.
         *
         * @return Result from adding Contact list.
         * - KErrNone if contact list add succeeds.
         * - KErrNotReady if notifier not started.
         * - KErrAlreadyExist if duplicate contact list.
         * - Else one of system wide error codes.
         */
        IMPORT_C TInt Add( const TDesC& aContactListName );


        /**
         * Removes contact list from the list of tracked contact lists.
         *
         * If the last contact list is removed, stops the notifier.
         *
         * @since 3.0
         * @param aContactListName Contact list which tracking to stop.
         *
         * @return Result from removing Presence ID.
         * - KErrNone if contact list remove succeeds.
         * - KErrNotReady if notifier not started.
         * - KErrNotFound if contact list not tracked.
         * - Else one of system wide error codes.
         */
        IMPORT_C TInt Remove( const TDesC& aContactListName );





        //-----------------------------------------------------------------------
    public: /* Contact list observers */


        /**
         * Registers observer to be notified from contact list changes.
         *
         * Observers are notified in their registeration order.
         * (First registerd notified first.)
         *
         * @param aObserver The observer to be notified.
         * @return KErrNone is observer added succesfully.
         *         Else one of the system wide error codes.
         */
        IMPORT_C TInt AddObserver(
            MPEngContactListObserver2& aObserver );



        /**
         * Unregisters contact list observer.
         *
         * @param aObserver The observer to remove.
         * @return KErrNone is observer removed succesfully.
         *         KErrNotFound if the observer wasn't registered.
         */
        IMPORT_C TInt RemoveObserver(
            MPEngContactListObserver2& aObserver );




        //-----------------------------------------------------------------------
    private: /* Data */


        //OWN: Implementation
        CPEngContactListNotifier2Imp*     iImp;

    };



#endif  //__CPENGCONTACTLISTNOTIFIER2_H

// End of File