/*
* 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: Contact list model interface & related definitions.
*
*/
#ifndef __MPENGCONTACTLIST2_H__
#define __MPENGCONTACTLIST2_H__
// INCLUDES
#include <E32Std.h>
#include <BaDescA.h>
#include <MPEngContactItem.h>
// DATA TYPES
/**
* Contact list sub views.
*
* @since 3.0
*/
enum TPEngContactListView
{
/**
* Contact list as it presented in the storage of the PEC engine
* This contact list contains also changes which has been
* done on the contact list, but haven't been yet commited to the
* Network server, therefore network version of the contact
* list can vary till the next update call.
* NOTE!
* Local and Network contact list are identical once
* Contact list is not editable
*/
EPEngCntListLocalView = 1,
/**
* Contact list as it exists on network server
* This is version of the contact list, as it was last time
* updated to the Network Server.
* Content is mostly same as EPEngCntListLocalVersion, unless
* there have been dome some changes on the contact list
* and client haven't updated them yet to the network.
* NOTE!
* Local and Network contact list are identical once
* Contact list is not editable
*/
EPEngCntListNetworkView = 2,
/**
* Contacts which were removed from the contact list.
* Those contact have been removed from the contact list
* within last update of the contact list to the network.
* Contact can be removed on demand of the Client, or network
* server can refuse contact item when it is tried to be added
* Contact are also removed when contact list update transaction
* fails for what ever reason.
* NOTE!
* Removed Contact are not defined for not editable contact lists
*/
EPEngRemovedContacts = 3,
/**
* Contacts which were added to the contact.
* Those contact have been added to the contact list
* within last update of the contact list to the network.
* Contact can be added on demand of the Client, or network
* server can also merge two contact into one, if they are same
* and it failed to be recognized by the client. For intance
* lack of knowledge of the Domain name.
* NOTE!
* Added Contact are not defined for not editable contact lists
*/
EPEngAddedContacts = 4
};
// CONSTANTS
/**
* Special case of the contact list created by the Server
* Content of the contact list is set of users subscribing
* presence of the loged user.
* Watcher List does not have to be available always, depends on
* the server user is logged in.
*/
_LIT( KPEngWatcherList, "watcherlist" );
// FORWARD DECLARATIONS
class MPEngContactListProperties;
// CLASS DECLARATION
/**
* General API for different contact lists.
*
* Interface allows users to manipulate and retrieve
* data from the contact list.
*
* @since 3.0
*/
class MPEngContactList2
{
public: // Mutators
/**
* Inserts a Contact into the Contact list.
*
* Each Contact can exist only once in the contact list.
* If added contact already exists in the contact list, function
* Leaves with KErrAlready exists.
* If Contact List nick name needs to be changed for contact,
* MPEngContactItem.h interface should be used instead.
* This function can also fail if some other client
* is already editing content of this contact list.
*
* Function leaves with KErrNoMemory, if there is insufficient
* memory available to perform operation.
*
* If the function leaves, the Contact list is left in the state
* it was before
*
* !NOTE!
* This function is not available for Non-Editable contact lists.
*
* @since 3.0
*
* @param aContact Contact to be added to the contact list
* @param aNickName nick name for the contact
* If nick name is not passed, no nick name is defined
* for the contact, same as KNullDesC value.
* @return The position within the contact list.
*/
virtual TInt AddContactL( const TDesC& aContact,
const TDesC& aNickName = KNullDesC ) = 0;
/**
* Removes Contact from the Contact list
*
* If contact does not exists in the contact list, function
* does nothing.
*
* Function leaves with KErrNoMemory, if there is insufficient
* memory available to perform operation.
*
* If the function leaves, the Contact list is left in the state
* it was before
*
* !NOTE!
* This function is not available for Non-Editable contact lists.
*
* @since 3.0
*
* @param aContact The contact to be removed from the Contact list
*/
virtual void RemoveContactL( const TDesC& aContact ) = 0;
/**
* Find Contact in the contact list
*
* Finds Contact in defined contact list.
* Search is performed with the comparison sense to
* Contact specifics and also smart domain comparison is employed
* if home domain is known to the system.
* By default search is performed on the Local contact list view
*
* !NOTE!
* Not all views are available for Non-Editable contact lists
*
* @since 3.0
*
* @param aContact contact to look for
* @param aView Contact list view to look for Contact in, by default
* Local contact list view is used
* @return position
*/
virtual TInt FindContact(
const TDesC& aContact,
TPEngContactListView aView
= EPEngCntListLocalView ) const = 0;
/**
* Count of the Contacts of the Contact list view
*
* Returns count of the contact IDs on the defined Contact List
* view.
* By default Local List view is used
*
* !NOTE!
* Not all views are available for Non-Editable contact lists
*
* @since 3.0
* @param aView Contact list view to get count for, by default
* Local contact list view is used
* @return Count of the Contact of the list
*/
virtual TInt Count( TPEngContactListView aView
= EPEngCntListLocalView ) const = 0;
/**
* Contact Item of the Contact list
*
* Gets reference to the particular contact item model
* of the contact list. This model can be used to view contact
* item details and modify them.
* Both const and non const overload available.
*
* There is no difference if contact item model was retrieved
* from Network or local view as far as contact item exists in
* both views.
*
* !NOTE!
* Contact Item can be retrieved only for Local and network
* Contact list view. Since there are not details
* available for Removed and Added contacts, except contact part,
* also editing of those lists is not allowed at any case.
* More about contact item model services can be seen in
* MPEngContactItem.h
*
* @since 3.0
* @param aIndex index of desired contact Item within list
* @param aSublist sublist of the contact list
* @return reference to contact Item model
*/
virtual MPEngContactItem& ContactItem(
TInt aIndex,
TPEngContactListView aView
= EPEngCntListLocalView ) = 0;
virtual const MPEngContactItem& ContactItem(
TInt aIndex,
TPEngContactListView aView
= EPEngCntListLocalView ) const = 0;
/**
* Contacts which were removed from the contact list
*
* List of the contact's WV Ids which were removed form the contact
* list, either on the clients demand or by the Network server
* Contacts can be also removed once update operation fails
*
* @since 3.0
* @return des array with removed contacts
*/
virtual const MDesCArray& RemovedContacts( ) const = 0;
/**
* Contacts which were added to the contact list
*
* List of the contact's WV Ids which were added to the contact
* list, either on the clients demand or by the Network server.
*
* @since 3.0
* @return des array with added contacts
*/
virtual const MDesCArray& AddedContacts( ) const = 0;
public: // Contact List properties
/**
* Contact list Settings
*
* Returns contact list properties model.
* This model can be used to view contact list
* details and also to edit certain parameters of the
* contact list which are allowed to be altered once
* contact list exists.
*
* @since 3.0
* @return Contact list properties model
*/
virtual MPEngContactListProperties& ListProperties() = 0;
public: // Functions for storage management
/**
* Remove all contacts from the contact list
*
* Cleans contact list from all Contacts
*
* @since 3.0
*/
virtual void RemoveAllContactsL( ) = 0;
/**
* Suspend contact list update notifications
*
* This should be used when client is intending to do lot
* of small changes of the contact list content and wants
* them to be notified to other clients all at once once
* editing is finished.
* Suspending is removed by calling ReleaseUpdateNotification()
*
* @since 3.0
*/
virtual void SuspendUpdateNotification( ) = 0;
/**
* Release sending of the contact list update notifications
*
* Update notifications are released and also all notifications
* which were ignored when suspend was active are now notified
*
* @since 3.0
*/
virtual void ReleaseUpdateNotification( ) = 0;
/**
* Roll back all changes
*
* All un-commited changes are rolled back and
* contact list is put in the state it exist on the network.
* This will roll back changes of the Contact Item edition
* and also Contact List Network related changes
*
* @since 3.0
* @return KErrNone if store of the roll back state was successful
* system wide error if storing failed
*/
virtual TInt RollBackAllChangesL( ) = 0;
/**
* Contact list locked by other client
*
* Returns ETrue if contact list has been locked by another
* client for editing of its content
*
* @since 3.0
* @return ETrue if Contact List is locked
*/
virtual TBool UpdateInProgress( ) const = 0;
/**
* Update of the contact list required
*
* Returns ETrue if contact list needs to be upated
*
* @since 3.0
* @return ETrue if update is needed. EFalse if not.
*/
virtual TBool UpdateRequired() const = 0;
protected: //Destructor
/**
* Virtual inline destructor.
* Protected destructor to prohibits deletion trough interface.
*/
virtual ~MPEngContactList2() {};
};
#endif // __MPENGCONTACTLIST2_H__
// End of File