diff -r 000000000000 -r 094583676ce7 PECengine/IncPresenceModel/MPEngContactList2.h --- /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 +#include +#include + + + +// 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 + + +