/*+
−
* 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+
−
+
−
+
−
+
−
+
−
+
−
+
−
+
−