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