/*
* 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__