--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/inc/CPEngAttributeStore2.h Wed Sep 01 12:31:13 2010 +0100
@@ -0,0 +1,380 @@
+/*
+* 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__
+