1 /*

     2 * Copyright (c) 2008 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:  Interface for presence cache reader.

    15 *

    16 */

    17 

    18 #ifndef MPRESENCECACHEREADER2_H

    19 #define MPRESENCECACHEREADER2_H

    20 

    21 #include <e32std.h>

    22 #include <e32base.h>

    23 #include <badesca.h>

    24 #include <presencecacheids.hrh>

    25 

    26 class MPresenceBuddyInfo2;

    27 class MPresenceCacheReadHandler2;

    28 

    29 /**

    30  * Interface for presence cache reader API. This interface is implemented 

    31  * by the Presence Cache client. Notice that an xsp id is

    32  * in the form ovi:xyz@example.com

    33  *

    34  * @since S60 v5.1

    35  */

    36 class MPresenceCacheReader2

    37     {

    38 public:

    39 

    40 

    41     /**

    42      * Factory method to instantiate MPresenceCacheReader.

    43      *

    44      * @return The new MPresenceCacheReader object. Object

    45      *         ownership is returned to caller.

    46      */

    47     IMPORT_C static MPresenceCacheReader2* CreateReaderL( );    

    48 

    49     /**

    50      * Public destructor.

    51      * Objects can be deleted through this interface.

    52      */

    53     virtual ~MPresenceCacheReader2() {};        

    54     

    55 

    56 public: //Sub interfaces for presence cache reader, Synchonous methods

    57 

    58     

    59     /**

    60      * Reads presence info from cache for a given identity, returns immediately.

    61      *

    62      * @param aIdentity buddy id, identity must be in xsp id format

    63      * @return MPresenceInfo for the given buddy. Ownership to caller.

    64      *         Null if service or buddy not found, not on Cleanup in that case.    

    65      */

    66     virtual MPresenceBuddyInfo2* PresenceInfoLC(const TDesC& aIdentity) = 0;

    67     

    68     /**

    69      * Returns total number of buddies stored in presence cache.

    70      * It includes all services, probably useful while deciding performance 

    71      * overheads or informing to the user.

    72      *

    73      * @return TInt Total number of presence infos in presence cache.

    74      */                           

    75     virtual TInt BuddyCountInAllServices() = 0;

    76     

    77     /**

    78      * Returns total number of buddies (presence infos) stored in a specific

    79      * service in presence cache. It includes only the given service. 

    80      *

    81      * @param aServiceName as in device's service table

    82      * @return TInt buddy count or error code. e.g. in case of service not

    83      *         found return value is KErrNotFound.

    84      */                           

    85     virtual TInt BuddyCountInService(const TDesC& aServiceName) = 0;

    86     

    87     /**

    88      * Returns total number services in presence cache.

    89      *

    90      * @return TInt total number of services in presence cache.

    91      */                           

    92     virtual TInt ServicesCount() = 0;

    93         

    94     /**

    95      * Cancels any async. read operation going on. After calling this

    96      * method no callback will be received from asycn read method.

    97      *

    98      * @return error code, KErrNone if successfully cancelled.

    99      */

   100     virtual TInt CancelRead() = 0;

   101                                                 

   102 

   103 public: //Sub interfaces for presence cache reader, Asynchronous methods

   104 

   105     /**

   106      * Reads all presence info from cache for a given service. Returns in 

   107      * MPresenceCacheReadHandler2's HandlePresenceReadL.

   108      *

   109      * @param aServiceName Service name to search from

   110      * @param aHandler to handle async. callback

   111      * @return error code, in case of error callback wont be called.

   112      */    

   113     virtual TInt AllBuddiesPresenceInService(const TDesC& aServiceName, 

   114                                 MPresenceCacheReadHandler2* aHandler) = 0;

   115 

   116 public: //Sub interfaces for presence cache reader, Asynchronous methods

   117     

   118     /**

   119      * Sets the observer to receive Presence Buddy Change notifications.

   120      * Observer must be set before using SubscribePresenceBuddyChangeL.

   121      * If client changes the observer using this method, all the notifications

   122      * related to existing and new subscriptions will be delivered to 

   123      * the new observer.

   124      *

   125      * @return Error code, if KErrNone observer is successfully set.

   126      */

   127     virtual TInt SetObserverForSubscribedNotifications(

   128         MPresenceCacheReadHandler2* aHandler) = 0;

   129     

   130     /**

   131      * Subscribe for given presence buddy's change in presence. An observer

   132      * must be set before using this method by SetObserverForSubscribedNotifications.

   133      * Notifcations are delivered through MPresenceCacheReadHandler2's HandlePresenceNotificationL

   134      *

   135      * @param aIdentity buddy id, identity must be in xsp id format

   136      * @return KErrNone if successful, KErrArgument if observer not set

   137      * @leave Only in system error cases e.g. if failed to allocate memory.

   138      */

   139     virtual TInt SubscribePresenceBuddyChangeL(const TDesC& aIdentity) = 0;

   140                                                 

   141     /**

   142      * Unsubscribe for given presence buddy's change in presence. The request

   143      * is ignored if invalid.

   144      *

   145      * @param aIdentity buddy id, identity must be in xsp id format

   146      * @leave Only in system error cases e.g. if failed to allocate memory.

   147      */

   148     virtual void UnSubscribePresenceBuddyChangeL(const TDesC& aIdentity) = 0;

   149 

   150     };

   151 

   152 #endif // MPRESENCECACHEREADER2_H

   153 

   154 

   155