/*

* 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 transaction environment.

*

*/

#ifndef __MPENGPRESENCEATTRTRANSACTIONENV_H

#define __MPENGPRESENCEATTRTRANSACTIONENV_H

//INCLUDES

#include <E32Std.h>

#include "BamDescA.h"

//FORWARD DECLARATIONS

class MPEngPresenceAttrModel2;

// CLASS DECLARATION

/**

 * Interface for Presence Attribute Transaction Environment.

 *

 * Attribute Transaction Environment manages the list

 * of subscribed presence attributes

 *

 * NOTE!!! Attribute Transaction Environment is reference counted singleton,

 * so client which has retrieved a instance to it, must also free it

 * by calling MPEngPresenceAttrTransactionEnv::Close()

 *

 * @lib 3.0

 */

class MPEngPresenceAttrTransactionEnv

    {

    public: //Reference cleanup

        /**

         * Attribute Transaction Environment is reference counted

         * singleton. and clients must free all obtained instances

         * by calling this to each of them when the Attribute

         * Transaction Environment isn't anymore needed.

         *

         * @since 3.0

         */

        virtual void Close() = 0;

    public: //Subscriptions

        /**

         * Adds given presence id into list of subscribed users.

         *

         * Subscriptions are "reference counted", so one subscribed

         * user can have several subscriptions active.

         * If given presence ID is empty, leaves with KErrArgument.

         *

         * @since 3.0

         * @param aPresenceID The subscribed users presence ID.

         */

        virtual void AddSubscriptionL( const TDesC& aPresenceID ) = 0;

        /**

         * Removes given user from attribute librarys list of

         * subscribed users.

         * Subscriptions are "reference counted", so one subscribed

         * user can have several subscriptions active.

         * ==> Subscribed user must be removed as many times

         * as it has been added.

         *

         * If given presence id is empty, does nothing.

         *

         * @since 3.0

         * @param aPresenceID The subscribed users presence ID.

         */

        virtual void RemoveSubscriptionL( const TDesC& aPresenceID ) = 0;

        /**

         * Gets the list of currently subscribed users.

         *

         * @since 3.0

         * @return The list if currently subscribed users.

         */

        virtual const MDesCArray& SubscribedPresenceIDs() const = 0;

    public: //Session attributes

        /**

         * Sets session tracing attributes.

         * Clears previous attributes and sets the new set in use.

         *

         * @since 3.0

         * @param aAttributeModels Session tracing attributes.

         * In success, takes the ownership of attributes which

         * are removed from parameter array.

         */

        virtual void SetSessionTracingAttributesL(

            RPointerArray< MPEngPresenceAttrModel2 >& aAttributeModels ) = 0;

        /**

         * Updates session tracing attributes. If attribute is found

         * from internal session tracing attributes list and also from

         * parameter array, takes the attribute from parameter array

         * away, and replaces the internal attribute object with

         * parameter one.

         *

         * @since 3.0

         * @param aAttributeModels New session tracing attributes.

         * In success, takes the ownership of attributes which

         * are removed from parameter array.

         */

        virtual void UpdateSessionTracingAttributesL(

            RPointerArray< MPEngPresenceAttrModel2 >& aAttributeModels ) = 0;

        /**

         * Informs held attributes about session state change

         * and then stores those back to storage.

         *

         * @since 3.0

         * @param aSessionOpen If ETrue, network presence session

         * was opened. If EFalse, network presence session was closed.

         */

        virtual void HandleNetworkSessionStateChangeL( TBool aSessionOpen ) = 0;

    public: //Orphan notifications

        /**

         * Adds a presence notification to orphan notification que.

         *

         * @since 3.0

         * @param aPresenceBlock The orphan notification to que.

         */

        virtual void QueOrphanNotificationL( const TDesC8& aPresenceBlock ) = 0;

        /**

         * Processes the qued orphan notifications.

         * Adds the generated attribute models to given array.

         *

         * @since 3.0

         * @param aModels The array to add produced attribute models.

         */

        virtual void ProcessOrphanNotificationsL(

            RPointerArray< MPEngPresenceAttrModel2 >& aModels ) = 0;

    protected:

        /**

         * Protected  destructor.

         *

         * Concrete Attribute Transaction Environment can't

         * be deleted through this interface.

         */

        virtual ~MPEngPresenceAttrTransactionEnv() {};

    };

#endif      //  __MPENGPRESENCEATTRTRANSACTIONENV_H

//  End of File