/*

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

*

*/

#ifndef MPRESENCECACHEREADER2_H

#define MPRESENCECACHEREADER2_H

#include <e32std.h>

#include <e32base.h>

#include <badesca.h>

#include <presencecacheids.hrh>

class MPresenceBuddyInfo2;

class MPresenceCacheReadHandler2;

/**

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

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

 * in the form ovi:xyz@example.com

 *

 * @since S60 v5.1

 */

class MPresenceCacheReader2

    {

public:

    /**

     * Factory method to instantiate MPresenceCacheReader.

     *

     * @return The new MPresenceCacheReader object. Object

     *         ownership is returned to caller.

     */

    IMPORT_C static MPresenceCacheReader2* CreateReaderL( );    

    /**

     * Public destructor.

     * Objects can be deleted through this interface.

     */

    virtual ~MPresenceCacheReader2() {};        

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

    /**

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

     *

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

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

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

     */

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

    /**

     * Returns total number of buddies stored in presence cache.

     * It includes all services, probably useful while deciding performance 

     * overheads or informing to the user.

     *

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

     */                           

    virtual TInt BuddyCountInAllServices() = 0;

    /**

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

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

     *

     * @param aServiceName as in device's service table

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

     *         found return value is KErrNotFound.

     */                           

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

    /**

     * Returns total number services in presence cache.

     *

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

     */                           

    virtual TInt ServicesCount() = 0;

    /**

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

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

     *

     * @return error code, KErrNone if successfully cancelled.

     */

    virtual TInt CancelRead() = 0;

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

    /**

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

     * MPresenceCacheReadHandler2's HandlePresenceReadL.

     *

     * @param aServiceName Service name to search from

     * @param aHandler to handle async. callback

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

     */    

    virtual TInt AllBuddiesPresenceInService(const TDesC& aServiceName, 

                                MPresenceCacheReadHandler2* aHandler) = 0;

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

    /**

     * Sets the observer to receive Presence Buddy Change notifications.

     * Observer must be set before using SubscribePresenceBuddyChangeL.

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

     * related to existing and new subscriptions will be delivered to 

     * the new observer.

     *

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

     */

    virtual TInt SetObserverForSubscribedNotifications(

        MPresenceCacheReadHandler2* aHandler) = 0;

    /**

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

     * must be set before using this method by SetObserverForSubscribedNotifications.

     * Notifcations are delivered through MPresenceCacheReadHandler2's HandlePresenceNotificationL

     *

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

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

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

     */

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

    /**

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

     * is ignored if invalid.

     *

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

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

     */

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

    };

#endif // MPRESENCECACHEREADER2_H