/*

* 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 presence attribute models.

*

*/

#ifndef __CPENGATTRIBUTESTORE2_H__

#define __CPENGATTRIBUTESTORE2_H__

// INCLUDES

#include <E32Base.h>

//FORWARD DECLARATIONS

class CPEngAttributeStore2Imp;

class CPEngNWSessionSlotID2;

class MPEngPresenceAttrModel2;

/**

 * Store API to retrieve presence attribute models.

 *

 * With this API clients can access presence attributes

 * from two different category:

 *

 *   1. Cached presence attributes

 *      Cached presence attributes are subscribed or fetched

 *      presence attributes stored to presence cache.

 *      Clients can only read values from these attributes.

 *      Cached attribute objects are available to clients

 *      only when attribute data is in the storage.

 *      (Attribute is either subscribed or fetched from network.)

 *      Cached data is available only during active network session.

 *

 *

 *   2. User own presence attributes

 *      Own presence attributes present the user own presence status.

 *      Presence Engine has always user own attributes defined.

 *      On terminal hold user own attributes are initially in their

 *      default state. Each concrete attribute type defines

 *      its own default state.

 *

 *      To user own presence attributes clients can perform:

 *      - edit user own presence attributes

 *      - store edited user own attributes back to presence storage

 *      - publish user own presence attributes to network

 *

 *      User own attributes are stored to permanent presence storage.

 *      User own attribuets have empty Presence ID. See

 *      KPEngUserOwnPresenceId from PEngPresenceEngineConsts2.h

 *

 *

 * When loading attribute objects, ownership of created

 * attribute objects is returned to caller.

 *

 * NOTE!! Attribute objects can't be pushed directly with

 * CleanupStack::PushL() to CleanupStack. CleanupStack consideres

 * MPEngPresenceAttrModel2 objects as TAny pointers and frees their

 * memory directly without deleting properly such objects. Thus clients

 * need to use CleanupClosePushL( *presenceAttrModel2 ) to push

 * retrieved objects to CleanupStack.

 *

 * @lib PEngManager2.lib

 * @since 3.0

 */

class CPEngAttributeStore2 : public CBase

    {

        //-----------------------------------------------------------------------

    public: /* Construction */

        /**

         * Instantiates CPEngAttributeStore2 object.

         *

         * Instantiates CPEngAttributeStore2 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 CPEngAttributeStore2 instance.

         */

        IMPORT_C static CPEngAttributeStore2* NewL(

            const CPEngNWSessionSlotID2& aNWSessionSlotID,

            TInt aPriority = CActive::EPriorityStandard );

        IMPORT_C static CPEngAttributeStore2* NewLC(

            const CPEngNWSessionSlotID2& aNWSessionSlotID,

            TInt aPriority = CActive::EPriorityStandard );

        /**

         * Destructor.

         * Virtual by CBase.

         */

        ~CPEngAttributeStore2();

    private:

        CPEngAttributeStore2();

        //-----------------------------------------------------------------------

    public: /* Cached presence attributes */

        /**

         * Gets a cached presence attribute.

         * Ownership of created model is transferred to caller.

         *

         * @since 3.0

         * @param aPresenceID The user's presence id

         * @param aType The attribute type. Presence Engine known

         *        attribute types are listed in PEngWVPresenceAttributes2.h.

         * @param aModel Returns retrieved attribute model. If retrieve

         *        fails with error, NULL pointer is returned.

         *        Ownership of created model is transferred to caller.

         *        Object can be destroyed either with normal delete operator

         *        or MPEngPresenceAttrModel2::Close() method. If CleanupStack

         *        is used, object must be pushed with CleanupClosePushL().

         *

         * @return Status code from attribute loading:

         *        - KErrNone if loading succeeds.

         *        - KErrNotSupported if attribute type isn't supported.

         *        - KErrNotFound if attribute isn't found from presence cache.

         *        - Else one of system wide error codes.

         */

        IMPORT_C TInt GetCachedAttribute(

            const TDesC& aPresenceID,

            TUint32 aType,

            MPEngPresenceAttrModel2*& aModel ) const;

        /**

         * Gets a cached presence attribute for editing.

         * Ownership of created model is transferred to caller.

         *

         * Loaded model can be read, edited and stored back to cache.

         *

         * Loading tries to gain exclusive write lock for attribute.

         * If some other client already has a exclusive write lock

         * for the attribute, the attribute model loading fails with

         * KErrLocked. Once write locked attribute stays locked until

         * the attribute model instance owning the lock is destroyed.

         *

         * @since 3.0

         * @param aType The attribute type. Presence Engine known

         *        attribute types are listed in PEngWVPresenceAttributes2.h.

         * @param aModel Returns retrieved attribute model. If retrieve

         *        fails with error, NULL pointer is returned.

         *        Ownership of created model is transferred to caller.

         *        Object can be destroyed either with normal delete operator

         *        or MPEngPresenceAttrModel2::Close() method. If CleanupStack

         *        is used, object must be pushed with CleanupClosePushL().

         *

         * @return Status code from attribute loading:

         *        - KErrNone if loading succeeds.

         *        - KErrNotSupported if attribute type isn't supported.

         *        - KErrLocked if attribute model is already locked.

         *        - Else one of system wide error codes.

         */

        IMPORT_C TInt GetAndLockCachedAttribute(

            const TDesC& aPresenceID,

            TUint32 aType,

            MPEngPresenceAttrModel2*& aModel );

        /**

         * Stores editable cached presence attribute to presence

         * storage. Ownership of model stays on the caller.

         * The attribute model edit lock is kept or released

         * depending the aReleaseEditLock parameter.

         *

         * @since 3.0

         * @param aModel The attribute model to store.

         * @param aKeepLocked If ETrue, attribute model

         * edit lock is released if storing succeeds. If EFalse,

         * attribute model is kept edit locked in all cases.

         * @return Status code from attribute storing:

         *         - KErrNone if storing succeeds.

         *         - KErrArgument if attribute is either loaded from another

         *           NWSessionSlot or it isn't locked for edit.

         *         - Else one of system wide error codes.

         */

        IMPORT_C TInt StoreCachedAttribute(

            MPEngPresenceAttrModel2& aModel,

            TBool aReleaseEditLock = ETrue );

        //-----------------------------------------------------------------------

    public: /* User own presence attributes  */

        /**

         * Gets a user own presence attribute for reading.

         * Ownership of created model is transferred to caller.

         *

         * Loaded model can be only read. If attribute value is tried

         * to edit or save to storage, those operations will fail with

         * error.

         *

         * @since 3.0

         * @param aType The attribute type. Presence Engine known

         *        attribute types are listed in PEngWVPresenceAttributes2.h.

         * @param aModel Returns retrieved attribute model. If retrieve

         *        fails with error, NULL pointer is returned.

         *        Ownership of created model is transferred to caller.

         *        Object can be destroyed either with normal delete operator

         *        or MPEngPresenceAttrModel2::Close() method. If CleanupStack

         *        is used, object must be pushed with CleanupClosePushL().

         *

         * @return Status code from attribute loading:

         *        - KErrNone if loading succeeds.

         *        - KErrNotSupported if attribute type isn't supported.

         *        - Else one of system wide error codes.

         */

        IMPORT_C TInt GetOwnAttribute(

            TUint32 aType,

            MPEngPresenceAttrModel2*& aModel ) const;

        /**

         * Gets a user own presence attribute for editing.

         * Ownership of created model is transferred to caller.

         *

         * Loaded model can be read or edited or published to network.

         *

         * Loading tries to gain exclusive write lock for attribute.

         * If some other client already has a exclusive write lock

         * for the attribute, the attribute model loading fails with

         * KErrLocked. Once write locked attribute stays locked until

         *  - the attribute model instance owning the lock is destroyed

         *  - the lock is freed with CPEngAttributeStore2::UnLockOwnAttribute()

         *  - the attribute model is published to network with

         *    CPEngAttributeTransaction2::PublishAndUnLockOwnAttribute()

         *

         * @since 3.0

         * @param aType The attribute type. Presence Engine known

         *        attribute types are listed in PEngWVPresenceAttributes2.h.

         * @param aModel Returns retrieved attribute model. If retrieve

         *        fails with error, NULL pointer is returned.

         *        Ownership of created model is transferred to caller.

         *        Object can be destroyed either with normal delete operator

         *        or MPEngPresenceAttrModel2::Close() method. If CleanupStack

         *        is used, object must be pushed with CleanupClosePushL().

         *

         * @return Status code from attribute loading:

         *        - KErrNone if loading succeeds.

         *        - KErrNotSupported if attribute type isn't supported.

         *        - KErrLocked if attribute model is already locked.

         *        - Else one of system wide error codes.

         */

        IMPORT_C TInt GetAndLockOwnAttribute(

            TUint32 aType,

            MPEngPresenceAttrModel2*& aModel );

        /**

         * Stores editable user own presence attribute to presence

         * storage. Ownership of model stays on the caller.

         * The attribute model edit lock is kept or released

         * depending the aReleaseEditLock parameter.

         *

         * @since 3.0

         * @param aModel The attribute model to store.

         * @param aKeepLocked If ETrue, attribute model

         * edit lock is released if storing succeeds. If EFalse,

         * attribute model is kept edit locked in all cases.

         * @return Status code from attribute storing:

         *         - KErrNone if storing succeeds.

         *         - KErrArgument if attribute is either loaded from another

         *           NWSessionSlot or it isn't locked for edit.

         *         - Else one of system wide error codes.

         */

        IMPORT_C TInt StoreOwnAttribute(

            MPEngPresenceAttrModel2& aModel,

            TBool aReleaseEditLock = ETrue );

        /**

         * Frees the write lock owned by the model.

         * Ownership of model stays on the caller.

         *

         * @since 3.0

         * @param aModel The attribute model which write lock to free.

         * @return Status code from attribute storing:

         *         - KErrNone if unlocking succeeds.

         *         - KErrArgument if attribute is either loaded from another

         *           NWSessionSlot or it isn't locked for edit. (In this case

         *           the lock isn't freed.)

         */

        IMPORT_C TInt UnLockOwnAttribute(

            MPEngPresenceAttrModel2& aModel );

        /**

         * Checks is the given user owned attribute

         * write locked or not.

         *

         * @since 3.0

         * @param aType The attribute type. Presence Engine known attribute

         *        types are listed in PEngWVPresenceAttributes2.h.

         * @return Status code from lock checking:

         *         - KErrNone if not locked.

         *         - KErrNotSupported if attribute type isn't supported.

         *         - KErrLocked if attribute model is locked.

         *         - Else one of system wide error codes.

         */

        IMPORT_C TInt OwnAttributeAvailable(

            TUint32 aType ) const;

        //-----------------------------------------------------------------------

    public: /* Common utilities */

        /**

         * Checks is the given attribute type supported or not.

         *

         * Attribute types that Presence Engine knows are listed

         * in PEngWVPresenceAttributes2.h. Support for some of

         * attribute types is variated with CenRep local variation

         * keys or depends from currently used WV CSP protocol version.

         *

         * This method can be used to check is certain attribute type

         * supported currently or not.

         *

         * @since 3.0

         * @param aType The attribute type. Presence Engine known attribute

         *        types are listed in PEngWVPresenceAttributes2.h.

         * @return Status code from lock checking:

         *         - KErrNone if attribute type is supported.

         *         - KErrNotSupported if attribute type isn't supported.

         */

        IMPORT_C TInt AttributeTypeSupported( TUint32 aType ) const;

        //-----------------------------------------------------------------------

    private: /* Data */

        //OWN: Implementation

        CPEngAttributeStore2Imp*     iImp;

    };

#endif      //  __CPENGATTRIBUTESTORE2_H__