/*
* 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:  Store API to retrieve contact list models.
*
*/

#ifndef __CPENGCONTACTLISTSTORE2_H__
#define __CPENGCONTACTLISTSTORE2_H__

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


//FORWARD DECLARATIONS
class MPEngContactList2;
class MPEngContactListProperties2;
class CPEngContactListStore2Imp;
class CPEngNWSessionSlotID2;
class TPEngContactListBaseSettings;
class MPEngContactListProperties;


/**
 * Store API to retrieve and manage contact lists.
 *
 * With this API clients can access, initialize
 * and manage presence contact lists.
 *
 * @lib PEngManager2.lib
 * @since 3.0
 */
class CPEngContactListStore2 : public CBase
    {
        //-----------------------------------------------------------------------
    public: /* Construction */

        /**
         * Instantiates CPEngContactListStore2 object.
         *
         * Instantiates CPEngContactListStore2 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 Presence Engine client side active
         * objects. These active objects are used when asynchronously delivering
         * events to observers or maintaining Presence Cache state.
         *
         * @return New CPEngContactListStore2 instance.
         */
        IMPORT_C static CPEngContactListStore2* NewL(
            const CPEngNWSessionSlotID2& aNWSessionSlotID,
            TInt aPriority = CActive::EPriorityStandard );

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


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



    private:

        CPEngContactListStore2();


        //-----------------------------------------------------------------------
    public: /* List of contact lists */


        /**
         * List of all contact lists. Contains both Presence Engine
         * native contact lists and unknown server contact lists.
         *
         * @since 3.0
         * @return List of all contact lists names. Contains both unknown
         *         server contact lists and Presence Engine local contact
         *         lists.
         */
        IMPORT_C const MDesCArray& AllContactListsL() const;



        /**
         * Contact list which content has been synchronized between
         * network and local client. Contact list models of such
         * a contact lists can be retrieved by the client and used.
         * This group of the contact list consist from the contact lists
         * of the native contact lists of the PEC engine and unknown
         * contact lists of the Network server.
         *
         * @since 3.0
         * @return List of active contact lists.
         */
        IMPORT_C const MDesCArray& SynchronizedContactListsL() const;




        //-----------------------------------------------------------------------
    public: /* Contact list access */


        /**
         * Gets a reference to presence contact list.
         *
         * Ownership of contact list remains on the Presence Engine.
         * Contact list is identified by its name defined when
         * the list was created or by the name how it exists on the
         * network server if the list is unknown server contact list.
         *
         * @since 3.0
         * @param aContactListName Name of the contact list.
         * @return Contact list. Client can read and edit the contact
         *         list contents. Edit results are automaticly preserved
         *         to Presence engine's storage.
         */
        IMPORT_C MPEngContactList2& ContactListL( const TDesC& aContactListName );





        //-----------------------------------------------------------------------
    public: /* Contact list management */


        /**
         * Creates a new contact list.
         *
         * Created new contact list is based on the:
         *  - contact list name
         *  - contact list base settings
         *
         * Created contact list is stored permanently and
         * it is made available for clients for next sessions.
         *
         * Method returns reference to contact list property interface.
         * Client can use this property interface to define further
         * contact list properties. If client doesn't set further
         * settings, default values are used.
         *
         * Contact list must be synchronized before the client can
         * use it freely.
         *
         * @see CPEngContactListTransaction2::SynchronizeContactList()
         *
         * @since 3.0
         * @param aContactListName Name for the new contact list.
         * @param aBaseSettings Base settings for the new contact list.
         * @return Reference to just created contact lists properties.
         * Properties ownership isn't returned.
         */
        IMPORT_C MPEngContactListProperties& CreateContactListL(
            const TDesC& aContactListName,
            TPEngContactListBaseSettings& aBaseSettings );


        /**
         * Deletes a contact list.
         *
         * Sets the contact list deleted, so it cannot be used anymore.
         * When the deleted contact list is synchronized with
         * the network server, it is also to deleted from
         * network server.
         *
         * @see CPEngContactListTransaction2::SynchronizeContactList()
         *
         * @since 3.0
         * @param aContactList Name of the contact list.
         */
        IMPORT_C void DeleteContactListL(
            const TDesC& aContactListName );

        /**
         *  Change contact list type
         *
         *  Contact list type is updated. Client does not have to retrieve
         *  again contact list model if it was retrieved before. Change
         *  is imidiate.
         *
         *  @since 3.0
         *  @param aContactList name of the contact list to change type
         *  @param aContactListType new type of the contact list.
         */
        IMPORT_C void ChangeContactListTypeL(
            const TDesC& aContactList,
            TPEngContactListType aContactListType );


        /**
         * Gets the contact list properties.
         *
         * Contact list properties interface allows to view
         * and edit contact list properties. Contact list
         * properties can be retrieved for all contact lists.
         *
         * If the contact list isn't synchronized with network
         * server, some of the details are not available.
         * Particularly  display name of the unknown server
         * contact lists is unavailable.
         *
         * @see CPEngContactListTransaction2::SynchronizeContactList()
         *
         * @since 3.0
         * @param aContactListName Name of the contact list.
         * @return Contact list properties.
         *         Properties ownership isn't returned.
         */
        IMPORT_C MPEngContactListProperties& ContactListPropertiesL(
            const TDesC& aContactListName );



        /**
         * Gets the contact list properties.
         *
         * Contact list properties interface allows to view
         * and edit contact list properties. Contact list
         * properties can be retrieved for all contact lists.
         *
         * If the contact list isn't synchronized with network
         * server, some of the details are not available.
         * Particularly  display name of the unknown server
         * contact lists is unavailable.
         *
         * @see CPEngContactListTransaction2::SynchronizeContactList()
         *
         * @since 3.0
         * @param aContactListName Name of the contact list.
         * @return Contact list properties.
         *         Properties ownership isn't returned.
         */
        IMPORT_C MPEngContactListProperties& DefaultContactListPropertiesL();


        /**
         * Sets a contact list as default contact list.
         *
         * To make selection effective, contact list must be
         * synchronized with network server.
         *
         * @see CPEngContactListTransaction2::SynchronizeContactList()
         *
         * @since 3.0
         * @param aContactListName Contact list to be set as default
         * contact list.
         */
        IMPORT_C void SetAsDefaultContactListL(
            const TDesC& aContactListName );




        //-----------------------------------------------------------------------
    public:  /* Contact list releasing */



        /**
         * Releases the contact list from the memory.
         *
         * Releases contact list from the client side memory.
         * Contact list can be still used by other clients.
         *
         * If client wants to use same contact list again,
         * it can be done by retrieving the list again with the
         * ContactListL() method.
         *
         * @since 3.0
         * @param aContactListName The contact list to be released.
         * @return Currently KErrNone.
         */
        IMPORT_C TInt ReleaseContactList( const TDesC& aContactListName );





        //-----------------------------------------------------------------------
    public: /* @deprecated contact lists management functions*/

        IMPORT_C const MDesCArray& ActiveContactListsL() const;
        IMPORT_C const MDesCArray& NativeContactListsL() const;
        IMPORT_C const MDesCArray& UnknownServerContactListsL() const;
        IMPORT_C TInt ReleaseUnknownContactListFromStore(
            const TDesC& aContactListName );





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


        //OWN: Implementation
        CPEngContactListStore2Imp*     iImp;
    };



#endif      //  __CPENGCONTACTLISTSTORE2_H__

//End of file