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