--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/PECengine/IncPresenceModel/MPEngContactList2.h Thu Dec 17 08:41:52 2009 +0200
@@ -0,0 +1,395 @@
+/*
+* 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
+
+
+