diff -r 000000000000 -r 094583676ce7 inc/CPEngContactListStore2.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/inc/CPEngContactListStore2.h Thu Dec 17 08:41:52 2009 +0200 @@ -0,0 +1,329 @@ +/* +* 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 +#include +#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