--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/inc/CPEngAttributeTransaction2.h Wed Sep 01 12:31:13 2010 +0100
@@ -0,0 +1,311 @@
+/*
+* 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: Presence attribute transactions.
+*
+*/
+
+#ifndef __CPENGATTRIBUTETRANSACTION2_H
+#define __CPENGATTRIBUTETRANSACTION2_H
+
+// INCLUDES
+#include <E32Base.h>
+#include <BamDescA.h>
+
+
+// FORWARD DECLARATIONS
+class CPEngAttributeTransaction2Imp;
+class CPEngNWSessionSlotID2;
+class MPEngAttributeTransactionObserver2;
+class MPEngPresenceAttrModel2;
+
+
+
+// CLASS DECLARATION
+
+/**
+ * Transaction API for presence attributes.
+ *
+ * With this API clients can:
+ *
+ * 1. Publish user own presence attributes to network.
+ * 2. Fetch presence attributes from network.
+ *
+ * Attribute publish and attribute fetch are asynchronous
+ * network operations, and their end results are signalled
+ * to given operation observer.
+ *
+ * @lib PEngManager2.lib
+ * @since 3.0
+ */
+class CPEngAttributeTransaction2 : public CBase
+ {
+
+ //-----------------------------------------------------------------------
+ public: /* Construction */
+
+ /**
+ * Instantiates CPEngAttributeTransaction2 object.
+ *
+ * Instantiates CPEngAttributeTransaction2 object and connects
+ * it to identified Presence Engine 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 CPEngAttributeTransaction2
+ * client side active objects. These active objects are used when
+ * asynchronously delivering events to observers.
+ *
+ * @return New CPEngAttributeTransaction2 instance.
+ */
+ IMPORT_C static CPEngAttributeTransaction2* NewL(
+ const CPEngNWSessionSlotID2& aNWSessionSlotID,
+ TInt aPriority = CActive::EPriorityStandard );
+
+ IMPORT_C static CPEngAttributeTransaction2* NewLC(
+ const CPEngNWSessionSlotID2& aNWSessionSlotID,
+ TInt aPriority = CActive::EPriorityStandard );
+
+
+ /**
+ * Destructor.
+ * Virtual by CBase.
+ */
+ ~CPEngAttributeTransaction2();
+
+
+
+ private:
+
+ CPEngAttributeTransaction2();
+
+
+
+
+ //-----------------------------------------------------------------------
+ public: /* User own attribute publish */
+
+
+ /**
+ * Tests is the publish already active.
+ *
+ * @since 3.0
+ * @return ETrue if operation is active. Else EFalse.
+ */
+ IMPORT_C TBool IsPublishOwnAttributesActive() const;
+
+
+
+ /**
+ * Publishes the user own attribute to the network server.
+ *
+ * Published attribute is kept locked untill the publish
+ * operation completes (either succesfully or with failure).
+ *
+ * There can be just one active publish operation at a time
+ * per one CPEngAttributeTransaction2 instance. However,
+ * there can be simultaneously several publish operations
+ * going on within one NWSessionSlot with distinct
+ * CPEngAttributeTransaction2 objects and distinct attribute sets.
+ *
+ * Takes ownership to passed model(s). If method returns error,
+ * the model(s) ownership remains on the client. In success sets
+ * the given model pointer to NULL or resets the parameter model
+ * array.
+ *
+ * Passed models must be loaded from same NWSessionSlot as
+ * CPEngAttributeTransaction2 is connected and attribute
+ * models must be locked for edit/publish.
+ *
+ * @since 3.0
+ * @param aModel The attribute model to publish.
+ * @param aObserver The observer to notify from attribute
+ * publish events.
+ *
+ * @return Result from initiating attribute publish:
+ * - KErrNone if attribute publish succesfully initiated.
+ * - KErrInUse if attribute publish already on going from object.
+ * - KErrArgument if attributes either loaded from another
+ * NWSessionSlot or they are not locked for edit.
+ * - Else one of system wide error codes.
+ */
+ IMPORT_C TInt PublishAndUnLockOwnAttribute(
+ MPEngPresenceAttrModel2*& aModel,
+ MPEngAttributeTransactionObserver2& aObserver );
+
+
+ IMPORT_C TInt PublishAndUnLockOwnAttributes(
+ RPointerArray<MPEngPresenceAttrModel2>& aModels,
+ MPEngAttributeTransactionObserver2& aObserver );
+
+
+
+ /**
+ * Cancels the user attribute publish.
+ *
+ * @since 3.0
+ */
+ IMPORT_C void CancelPublishOwnAttributes();
+
+
+
+
+
+ //-----------------------------------------------------------------------
+ public: /* Presence attribute fetch from network */
+
+ /**
+ * Tests is the fetch already active.
+ *
+ * @since 3.0
+ * @return ETrue if operation is active. Else EFalse.
+ */
+ IMPORT_C TBool IsFetchAttributesActive() const;
+
+
+ /**
+ * Fetches presence attributes from network server.
+ *
+ * Fetches presence attributes from the network
+ * and stores fetched attributes to presence cache.
+ * (Fetched presence attributes can be retrieved e.g. with
+ * CPEngAttributeStore2::GetCachedAttributeL().)
+ *
+ * There can be just one active fetch operation at a time
+ * per one CPEngAttributePublisher instance. However, within
+ * one NWSessionSlot there can be several active fetch
+ * operations going on.
+ *
+ * @since 3.0
+ * @param aPresenceID The user to fetch.
+ * @param aType The attribute type. Presence Engine known
+ * attribute types are listed in PEngWVPresenceAttributes2.h.
+ * @param aObserver The observer to notify from attribute fetch events.
+ * @param aOptions Reserved for future fetch options.
+ *
+ * @return Result from initiating attribute fetch:
+ * - KErrNone if attribute fetch succesfully initiated.
+ * - KErrInUse if attribute fetch already on going from object.
+ * - KErrNotSupported if requestSed attribute type isn't supported.
+ * - Else one of system wide error codes.
+ */
+ IMPORT_C TInt FetchAttributesToCache(
+ const TDesC& aPresenceID,
+ const TArray<TUint32>& aTypes,
+ MPEngAttributeTransactionObserver2& aObserver,
+ TInt aOptions = 0 );
+
+ IMPORT_C TInt FetchAttributesToCache(
+ const MDesCArray& aPresenceIDs,
+ const TArray<TUint32>& aTypes,
+ MPEngAttributeTransactionObserver2& aObserver,
+ TInt aOptions = 0 );
+
+
+ /**
+ * Fetches presence attributes from network server.
+ *
+ * Fetches presence attributes from the network
+ * and returns them to client as local objects.
+ * Client can ask the fetched presence attributes
+ * after succesfull fetch from
+ * CPEngAttributeTransaction2::GetFetchedAttributes().)
+ *
+ * There can be just one active fetch operation at a time
+ * per one CPEngAttributePublisher instance. However, within
+ * one NWSessionSlot there can be several active fetch
+ * operations going on.
+ *
+ * @since 3.0
+ * @param aPresenceID The user to fetch.
+ * @param aType The attribute type. Presence Engine known
+ * attribute types are listed in PEngWVPresenceAttributes2.h.
+ * @param aObserver The observer to notify from attribute fetch events.
+ * @return Result from initiating attribute fetch:
+ * - KErrNone if attribute fetch succesfully initiated.
+ * - KErrInUse if attribute fetch already on going from object.
+ * - KErrNotSupported if requestSed attribute type isn't supported.
+ * - Else one of system wide error codes.
+ */
+ IMPORT_C TInt FetchAttributesToObjects(
+ const TDesC& aPresenceID,
+ const TArray<TUint32>& aTypes,
+ MPEngAttributeTransactionObserver2& aObserver );
+
+
+ /**
+ * Cancels the presence attribute fetch.
+ *
+ * @since 3.0
+ */
+ IMPORT_C void CancelFetchAttributes();
+
+
+
+ //-----------------------------------------------------------------------
+ public: /* Object get for observer callbacks */
+
+
+ /**
+ * Gets the fetched attribute objects produced by the last
+ * FetchAttributesToObjects(). Ownership of attribute models is
+ * returned to caller. Returned models can be only read.
+ *
+ * Fetched attributes can be asked only during the observer callback:
+ * MPEngAttributeTransactionObserver2::HandleAttributeTransactionCompleteL().
+ * After retrieving the models, client owns the attribute objects and
+ * can freely control their lifetime.
+ *
+ * @since 3.0
+ * @param aModel Returns retrieved attribute model(s).
+ * Retrieved attribute models are appended to the end of array.
+ * If array has existing attribute objects, those are not touched.
+ * If get fails with resource error, so far succesfully
+ * moved attributes are returned.
+ *
+ * @return Status code from attribute getting:
+ * - KErrNone if get succeeds.
+ * - KErrNotReady if no fetch results available
+ * - Else one of system wide error codes.
+ */
+ IMPORT_C TInt GetFetchedAttributes(
+ RPointerArray< MPEngPresenceAttrModel2 >& aModels );
+
+
+
+
+ //-----------------------------------------------------------------------
+ private: /* Data */
+
+
+ //OWN: Implementation
+ CPEngAttributeTransaction2Imp* iImp;
+
+
+ };
+
+#endif // __CPENGATTRIBUTETRANSACTION2_H
+
+//End of file
+
+
+
+
+
+
+