--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/inc/CPEngContactListStore2.h Wed Sep 01 12:31:13 2010 +0100
@@ -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 <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