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:  Notifier API to listen presence contact list changes.

    15 *

    16 */

    17 

    18 #ifndef __CPENGCONTACTLISTNOTIFIER2_H

    19 #define __CPENGCONTACTLISTNOTIFIER2_H

    20 

    21 

    22 //  INCLUDES

    23 #include <E32Base.h>

    24 #include <BamDescA.h>

    25 

    26 

    27 //FORWARD DECLARATIONS

    28 class MPEngContactListObserver2;

    29 class MPEngContactList2;

    30 class CPEngContactListNotifier2Imp;

    31 class CPEngNWSessionSlotID2;

    32 

    33 

    34 

    35 // CLASS DECLARATION

    36 

    37 /**

    38  * Notifier API for presence contact list changes.

    39  *

    40  * With this API clients can

    41  * 1. Receive notifications from changes in presence

    42  *    contact lists contents (users added or removed).

    43  *

    44  * 2. Receive notifications from changes in presence

    45  *    contact lists settings.

    46  *

    47  * @lib PEngManager2.lib

    48  * @since 3.0

    49  */

    50 class CPEngContactListNotifier2 : public CBase

    51     {

    52         //-----------------------------------------------------------------------

    53     public: /* Construction */

    54 

    55         /**

    56          * Instantiates CPEngContactListNotifier2 object.

    57          *

    58          * Instantiates CPEngContactListNotifier2 object and connects it to

    59          * identified Presence Engine side NWSessionSlot. NWSessionSlot

    60          * must be a valid, existing slot.

    61          *

    62          * Errors:

    63          *  - Requested NWSessionSlot not found: KErrNotFound

    64          *  - Given NWSessionSlotID malformed: KErrArgument

    65          *

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

    67          * session slot.

    68          * @param aPriority The priority for CPEngPresenceNotifier2

    69          * client side active objects. These active objects are used when

    70          * asynchronously delivering events to observers.

    71          *

    72          * @return New CPEngPresenceNotifier2 instance.

    73          */

    74         IMPORT_C static CPEngContactListNotifier2* NewL(

    75             const CPEngNWSessionSlotID2& aNWSessionSlotID,

    76             TInt aPriority = CActive::EPriorityStandard );

    77 

    78         IMPORT_C static CPEngContactListNotifier2* NewLC(

    79             const CPEngNWSessionSlotID2& aNWSessionSlotID,

    80             TInt aPriority = CActive::EPriorityStandard );

    81 

    82 

    83         /**

    84          * Destructor.

    85          * Virtual by CBase.

    86          */

    87         ~CPEngContactListNotifier2();

    88 

    89 

    90 

    91     protected:

    92 

    93         CPEngContactListNotifier2();

    94 

    95 

    96 

    97 

    98         //-----------------------------------------------------------------------

    99     public: /* Basic contact list notifier */

   100 

   101         /**

   102          * Check if the notifier is active.

   103          *

   104          * @since 3.0

   105          * @return ETrue if the notifier is active. Else EFalse.

   106          */

   107         IMPORT_C TBool IsActive() const;

   108 

   109 

   110 

   111         /**

   112          * Starts observing contact list changes.

   113          *

   114          * @since 3.0

   115          * @param aContactListName Contact list(s) which changes to track.

   116          * @return Result from observer start.

   117          * - KErrNone if notifier start succeeds.

   118          * - KErrInUse if notifier already started.

   119          * - KErrAlreadyExist if duplicate contact lists given.

   120          * - Else one of system wide error codes.

   121          */

   122         IMPORT_C TInt Start( const TDesC& aContactListName );

   123         IMPORT_C TInt Start( const MDesCArray& aContactListNames );

   124 

   125 

   126         /**

   127          * Stops observing contact list changes.

   128          *

   129          * @since 3.0

   130          */

   131         IMPORT_C void Stop();

   132 

   133 

   134 

   135 

   136 

   137         //-----------------------------------------------------------------------

   138     public: /* Advanced notifier features */

   139 

   140 

   141         /**

   142          * Adds contact list to the list of tracked contact lists.

   143          *

   144          * @since 3.0

   145          * @param aContactListName Contact list which changes to track.

   146          *

   147          * @return Result from adding Contact list.

   148          * - KErrNone if contact list add succeeds.

   149          * - KErrNotReady if notifier not started.

   150          * - KErrAlreadyExist if duplicate contact list.

   151          * - Else one of system wide error codes.

   152          */

   153         IMPORT_C TInt Add( const TDesC& aContactListName );

   154 

   155 

   156         /**

   157          * Removes contact list from the list of tracked contact lists.

   158          *

   159          * If the last contact list is removed, stops the notifier.

   160          *

   161          * @since 3.0

   162          * @param aContactListName Contact list which tracking to stop.

   163          *

   164          * @return Result from removing Presence ID.

   165          * - KErrNone if contact list remove succeeds.

   166          * - KErrNotReady if notifier not started.

   167          * - KErrNotFound if contact list not tracked.

   168          * - Else one of system wide error codes.

   169          */

   170         IMPORT_C TInt Remove( const TDesC& aContactListName );

   171 

   172 

   173 

   174 

   175 

   176         //-----------------------------------------------------------------------

   177     public: /* Contact list observers */

   178 

   179 

   180         /**

   181          * Registers observer to be notified from contact list changes.

   182          *

   183          * Observers are notified in their registeration order.

   184          * (First registerd notified first.)

   185          *

   186          * @param aObserver The observer to be notified.

   187          * @return KErrNone is observer added succesfully.

   188          *         Else one of the system wide error codes.

   189          */

   190         IMPORT_C TInt AddObserver(

   191             MPEngContactListObserver2& aObserver );

   192 

   193 

   194 

   195         /**

   196          * Unregisters contact list observer.

   197          *

   198          * @param aObserver The observer to remove.

   199          * @return KErrNone is observer removed succesfully.

   200          *         KErrNotFound if the observer wasn't registered.

   201          */

   202         IMPORT_C TInt RemoveObserver(

   203             MPEngContactListObserver2& aObserver );

   204 

   205 

   206 

   207 

   208         //-----------------------------------------------------------------------

   209     private: /* Data */

   210 

   211 

   212         //OWN: Implementation

   213         CPEngContactListNotifier2Imp*     iImp;

   214 

   215     };

   216 

   217 

   218 

   219 #endif  //__CPENGCONTACTLISTNOTIFIER2_H

   220 

   221 // End of File

   222 

   223 

   224