1 /*

     2 * Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Store API to retrieve contact list models.

    15 *

    16 */

    17 

    18 #ifndef __CPENGCONTACTLISTSTORE2_H__

    19 #define __CPENGCONTACTLISTSTORE2_H__

    20 

    21 // INCLUDES

    22 #include <E32Base.h>

    23 #include <BamDescA.h>

    24 #include "TPEngContactListBaseSettings.h"

    25 

    26 

    27 //FORWARD DECLARATIONS

    28 class MPEngContactList2;

    29 class MPEngContactListProperties2;

    30 class CPEngContactListStore2Imp;

    31 class CPEngNWSessionSlotID2;

    32 class TPEngContactListBaseSettings;

    33 class MPEngContactListProperties;

    34 

    35 

    36 /**

    37  * Store API to retrieve and manage contact lists.

    38  *

    39  * With this API clients can access, initialize

    40  * and manage presence contact lists.

    41  *

    42  * @lib PEngManager2.lib

    43  * @since 3.0

    44  */

    45 class CPEngContactListStore2 : public CBase

    46     {

    47         //-----------------------------------------------------------------------

    48     public: /* Construction */

    49 

    50         /**

    51          * Instantiates CPEngContactListStore2 object.

    52          *

    53          * Instantiates CPEngContactListStore2 object and connects it to

    54          * identified Presence Engine side NWSessionSlot. NWSessionSlot

    55          * must be a valid, existing slot.

    56          *

    57          * Errors:

    58          *  - Requested NWSessionSlot not found: KErrNotFound

    59          *  - Given NWSessionSlotID malformed: KErrArgument

    60          *

    61          * @param aNWSessionSlotID The session slot ID to identify the

    62          * session slot.

    63          * @param aPriority The priority for Presence Engine client side active

    64          * objects. These active objects are used when asynchronously delivering

    65          * events to observers or maintaining Presence Cache state.

    66          *

    67          * @return New CPEngContactListStore2 instance.

    68          */

    69         IMPORT_C static CPEngContactListStore2* NewL(

    70             const CPEngNWSessionSlotID2& aNWSessionSlotID,

    71             TInt aPriority = CActive::EPriorityStandard );

    72 

    73         IMPORT_C static CPEngContactListStore2* NewLC(

    74             const CPEngNWSessionSlotID2& aNWSessionSlotID,

    75             TInt aPriority = CActive::EPriorityStandard );

    76 

    77 

    78         /**

    79          * Destructor.

    80          * Virtual by CBase.

    81          */

    82         ~CPEngContactListStore2();

    83 

    84 

    85 

    86     private:

    87 

    88         CPEngContactListStore2();

    89 

    90 

    91         //-----------------------------------------------------------------------

    92     public: /* List of contact lists */

    93 

    94 

    95         /**

    96          * List of all contact lists. Contains both Presence Engine

    97          * native contact lists and unknown server contact lists.

    98          *

    99          * @since 3.0

   100          * @return List of all contact lists names. Contains both unknown

   101          *         server contact lists and Presence Engine local contact

   102          *         lists.

   103          */

   104         IMPORT_C const MDesCArray& AllContactListsL() const;

   105 

   106 

   107 

   108         /**

   109          * Contact list which content has been synchronized between

   110          * network and local client. Contact list models of such

   111          * a contact lists can be retrieved by the client and used.

   112          * This group of the contact list consist from the contact lists

   113          * of the native contact lists of the PEC engine and unknown

   114          * contact lists of the Network server.

   115          *

   116          * @since 3.0

   117          * @return List of active contact lists.

   118          */

   119         IMPORT_C const MDesCArray& SynchronizedContactListsL() const;

   120 

   121 

   122 

   123 

   124         //-----------------------------------------------------------------------

   125     public: /* Contact list access */

   126 

   127 

   128         /**

   129          * Gets a reference to presence contact list.

   130          *

   131          * Ownership of contact list remains on the Presence Engine.

   132          * Contact list is identified by its name defined when

   133          * the list was created or by the name how it exists on the

   134          * network server if the list is unknown server contact list.

   135          *

   136          * @since 3.0

   137          * @param aContactListName Name of the contact list.

   138          * @return Contact list. Client can read and edit the contact

   139          *         list contents. Edit results are automaticly preserved

   140          *         to Presence engine's storage.

   141          */

   142         IMPORT_C MPEngContactList2& ContactListL( const TDesC& aContactListName );

   143 

   144 

   145 

   146 

   147 

   148         //-----------------------------------------------------------------------

   149     public: /* Contact list management */

   150 

   151 

   152         /**

   153          * Creates a new contact list.

   154          *

   155          * Created new contact list is based on the:

   156          *  - contact list name

   157          *  - contact list base settings

   158          *

   159          * Created contact list is stored permanently and

   160          * it is made available for clients for next sessions.

   161          *

   162          * Method returns reference to contact list property interface.

   163          * Client can use this property interface to define further

   164          * contact list properties. If client doesn't set further

   165          * settings, default values are used.

   166          *

   167          * Contact list must be synchronized before the client can

   168          * use it freely.

   169          *

   170          * @see CPEngContactListTransaction2::SynchronizeContactList()

   171          *

   172          * @since 3.0

   173          * @param aContactListName Name for the new contact list.

   174          * @param aBaseSettings Base settings for the new contact list.

   175          * @return Reference to just created contact lists properties.

   176          * Properties ownership isn't returned.

   177          */

   178         IMPORT_C MPEngContactListProperties& CreateContactListL(

   179             const TDesC& aContactListName,

   180             TPEngContactListBaseSettings& aBaseSettings );

   181 

   182 

   183         /**

   184          * Deletes a contact list.

   185          *

   186          * Sets the contact list deleted, so it cannot be used anymore.

   187          * When the deleted contact list is synchronized with

   188          * the network server, it is also to deleted from

   189          * network server.

   190          *

   191          * @see CPEngContactListTransaction2::SynchronizeContactList()

   192          *

   193          * @since 3.0

   194          * @param aContactList Name of the contact list.

   195          */

   196         IMPORT_C void DeleteContactListL(

   197             const TDesC& aContactListName );

   198 

   199         /**

   200          *  Change contact list type

   201          *

   202          *  Contact list type is updated. Client does not have to retrieve

   203          *  again contact list model if it was retrieved before. Change

   204          *  is imidiate.

   205          *

   206          *  @since 3.0

   207          *  @param aContactList name of the contact list to change type

   208          *  @param aContactListType new type of the contact list.

   209          */

   210         IMPORT_C void ChangeContactListTypeL(

   211             const TDesC& aContactList,

   212             TPEngContactListType aContactListType );

   213 

   214 

   215         /**

   216          * Gets the contact list properties.

   217          *

   218          * Contact list properties interface allows to view

   219          * and edit contact list properties. Contact list

   220          * properties can be retrieved for all contact lists.

   221          *

   222          * If the contact list isn't synchronized with network

   223          * server, some of the details are not available.

   224          * Particularly  display name of the unknown server

   225          * contact lists is unavailable.

   226          *

   227          * @see CPEngContactListTransaction2::SynchronizeContactList()

   228          *

   229          * @since 3.0

   230          * @param aContactListName Name of the contact list.

   231          * @return Contact list properties.

   232          *         Properties ownership isn't returned.

   233          */

   234         IMPORT_C MPEngContactListProperties& ContactListPropertiesL(

   235             const TDesC& aContactListName );

   236 

   237 

   238 

   239         /**

   240          * Gets the contact list properties.

   241          *

   242          * Contact list properties interface allows to view

   243          * and edit contact list properties. Contact list

   244          * properties can be retrieved for all contact lists.

   245          *

   246          * If the contact list isn't synchronized with network

   247          * server, some of the details are not available.

   248          * Particularly  display name of the unknown server

   249          * contact lists is unavailable.

   250          *

   251          * @see CPEngContactListTransaction2::SynchronizeContactList()

   252          *

   253          * @since 3.0

   254          * @param aContactListName Name of the contact list.

   255          * @return Contact list properties.

   256          *         Properties ownership isn't returned.

   257          */

   258         IMPORT_C MPEngContactListProperties& DefaultContactListPropertiesL();

   259 

   260 

   261         /**

   262          * Sets a contact list as default contact list.

   263          *

   264          * To make selection effective, contact list must be

   265          * synchronized with network server.

   266          *

   267          * @see CPEngContactListTransaction2::SynchronizeContactList()

   268          *

   269          * @since 3.0

   270          * @param aContactListName Contact list to be set as default

   271          * contact list.

   272          */

   273         IMPORT_C void SetAsDefaultContactListL(

   274             const TDesC& aContactListName );

   275 

   276 

   277 

   278 

   279         //-----------------------------------------------------------------------

   280     public:  /* Contact list releasing */

   281 

   282 

   283 

   284         /**

   285          * Releases the contact list from the memory.

   286          *

   287          * Releases contact list from the client side memory.

   288          * Contact list can be still used by other clients.

   289          *

   290          * If client wants to use same contact list again,

   291          * it can be done by retrieving the list again with the

   292          * ContactListL() method.

   293          *

   294          * @since 3.0

   295          * @param aContactListName The contact list to be released.

   296          * @return Currently KErrNone.

   297          */

   298         IMPORT_C TInt ReleaseContactList( const TDesC& aContactListName );

   299 

   300 

   301 

   302 

   303 

   304         //-----------------------------------------------------------------------

   305     public: /* @deprecated contact lists management functions*/

   306 

   307         IMPORT_C const MDesCArray& ActiveContactListsL() const;

   308         IMPORT_C const MDesCArray& NativeContactListsL() const;

   309         IMPORT_C const MDesCArray& UnknownServerContactListsL() const;

   310         IMPORT_C TInt ReleaseUnknownContactListFromStore(

   311             const TDesC& aContactListName );

   312 

   313 

   314 

   315 

   316 

   317         //-----------------------------------------------------------------------

   318     private: /* Data */

   319 

   320 

   321         //OWN: Implementation

   322         CPEngContactListStore2Imp*     iImp;

   323     };

   324 

   325 

   326 

   327 #endif      //  __CPENGCONTACTLISTSTORE2_H__

   328 

   329 //End of file