/*

* 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 Manager.

*

*/

#ifndef __MPENGPRESENCEATTRMANAGER_H

#define __MPENGPRESENCEATTRMANAGER_H

//INCLUDES

#include <E32std.h>

#include "BaMDescA.h"

#include "BaDescA.h"

//DATA TYPES

/**

* Attribute instance options.

*

* @since 3.0

*/

enum TPEngAttributeInstanceOptions

    {

    ///

    EPEngInstanceOptionsNone  = 0x0,

    ///

    EPEngUserAttribute        = 0x00000001,

    ///

    EPEngStorableModel        = 0x00000002,

    ///

    EPEngEditLockedModel      = 0x00000004,

    ///

    EPEngCreationNotAllowed   = 0x00000008,

    };

//FORWARD DECLARATIONS

class MPEngPresenceAdvancedAttrModel2;

class MPEngPresenceAttrModel2;

// CLASS DECLARATION

/**

 * Interface for Presence Attribute Manager.

 *

 * NOTE!!! Attribute Manager is reference counted singleton, so client

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

 * by calling MPEngPresenceAttrManager::Close(), when the manager isn't

 * needed anymore.

 *

 * @since 3.0

 */

class MPEngPresenceAttrManager

    {

    public: //Reference cleanup

        /**

         * Attribute Manager is reference counted singleton.

         * and clients must free all obtained instances by

         * calling this to each of them when the Attribute Manager

         * isn't anymore needed.

         *

         * @since 3.0

         */

        virtual void Close() = 0;

    public: //Attribute model

        /**

         * Instantiates attribute model.

         *

         * @since 3.0

         * @param aModel On the return the instantiated attribute model.

         * Returned model is pushed on the CleanupStack. Returns ownership.

         * @param aPresenceID The attribute owners presence ID.

         * @param aType Presence attribute type.

         * @param aInstanceGenre The instance genre for new attribute instance.

         */

        virtual void InstantiateAttributeLC( MPEngPresenceAttrModel2*& aModel,

                                             const TDesC& aPresenceID,

                                             TUint32 aType,

                                             TInt aInstanceOptions ) = 0;

        /**

         * Instantiates and loads attribute model.

         *

         * @since 3.0

         * @param aModel On the return the loaded attribute model.

         * Returned model is pushed on the CleanupStack. Returns ownership.

         * @param aPresenceID The attribute owners presence ID.

         * @param aType Presence attribute type.

         * @param aInstanceGenre The instance genre for new attribute instance.

         * @return Was the model found from storage?

         * KErrNotFound if attribute wasn't found from storage.

         * Else KErrNone.

         */

        virtual TInt LoadAttributeLC( MPEngPresenceAttrModel2*& aModel,

                                      const TDesC& aPresenceID,

                                      TUint32 aType,

                                      TInt aInstanceOptions ) = 0;

        /**

         * Stores attribute model to storage.

         *

         * @since 3.0

         * @param aModel The model to store.

         */

        virtual void StoreEditLockedAttributeL( const MPEngPresenceAttrModel2& aModel ) = 0;

        /**

         * Releases the edit support from the attribute model.

         *

         * @since 3.0

         * @param aModel The model.

         * @return Error code.

         */

        virtual TInt StopEditSupport( MPEngPresenceAttrModel2& aModel ) const = 0;

        /**

         * Checks is the attribute model edit locked from

         * the same slot as the Attribute Manager is connected.

         *

         * @since 3.0

         * @param aModel The model.

         */

        virtual void ModelEditLockedFromThisSlotL(

            const MPEngPresenceAttrModel2& aModel ) const = 0;

    public: //Attribute type information

        /**

         * Tests is the passed attribute type id a valid network attribute

         * or not. Returns:

         * - KErrNone if the attribute type is a valid network attribute.

         * - KErrUnknown if the attribute id is unknown.

         * - KErrNotSupported if the attribute id is known,

         *   but the attribute isn't a valid network attribute

         *   (Attribute is a local attribute.)

         *

         * Attribute type is a valid network attribute if it's originator

         * is one of following:

         *  - EPEngClientOriginated

         *  - EPEngServerOriginated

         *  - EPEngClientServerOriginated

         *

         * @since 3.0

         * @param aType the type of the attribute.

         * @return KErrNone, KErrUnknown or KErrNotSupported.

         */

        virtual TInt ValidNetworkAttribute( TUint32 aType ) const = 0;

        /**

         * Returns the generic array holding all known attribute types.

         *

         * @since 3.0

         * @return The generic array holding all known attribute types.

         */

        virtual TArray<TUint32> KnownAttributeTypes() const = 0;

        /**

         * Gets the XML name and XML namespace for certain attribute type.

         * If the attribute type isn't known, returns KErrUnknown and empty

         * string as name and namespace.

         *

         * @since 3.0

         * @param aAttributeType The attribute type for which to get name and namespace.

         * @param aAttributeName On the return contains the asked attribute's XML name.

         * @param aAttributeName On the return contains the asked attribute's XML namespace.

         * @return KErrNone if the attribute type is known, else KErrUnknown.

         */

        virtual TInt GetAttributeXmlNameAndNameSpace( TUint32 aType,

                                                      TPtrC8& aAttributeName,

                                                      TPtrC8& aAttributeNameSpace ) const = 0;

    public: // Attribute request packing

        /**

         * Packs a attribute model array to buffer.

         *

         * @since 3.0

         * @param aModels Models to pack.

         * @return Heap buffer containing models data.

         * Buffer ownership is returned to caller.

         */

        virtual HBufC16* PackModelArrayL(

            const RPointerArray<MPEngPresenceAttrModel2>& aModels ) const = 0;

        /**

         * Extracts models from package.

         *

         * @since 3.0

         * @param aModelPkg Model package to extract.

         * @param aInstanceOptions Instance options

         * for instantiated attribute models.

         * @param aModels On the return contains extracted attribute models.

         * Models are appended to array.

         */

        virtual void UnpackModelArrayL(

            const TDesC16& aModelPkg,

            TInt aInstanceOptions,

            RPointerArray<MPEngPresenceAttrModel2>& aModels ) = 0;

        /**

         * Packs a attribute fetch request.

         *

         * @since 3.0

         * @param aPresenceIDs Presence ID's to pack.

         * @param aTypes Attribute types to pack.

         * @return Heap buffer containing fetch request data.

         * Buffer ownership is returned to caller.

         */

        virtual HBufC16* PackFetchRequestL( const MDesCArray& aPresenceIDs,

                                            const TArray<TUint32>& aTypes ) const = 0;

        /**

         * Extracts a attribute fetch request from package.

         *

         * @since 3.0

         * @param aFetchRequestPkg Attribute fetch request package to extract.

         * @param aPresenceIDs On the return contains extracted Presence IDs.

         * Presence IDs are appended to the end of array.

         * @param aTypes On the return contains extracted attribute type IDs.

         * Attribute types are appended to the end of array.

         */

        virtual void UnpackFetchRequestL( const TDesC16& aFetchRequestPkg,

                                          CDesCArray& aPresenceIDs,

                                          RArray<TUint32>& aTypes ) const = 0;

    public: // Attribute store ID handling

        /**

         * Generates a attribute store id from given

         * attribute type and presence id. Returns store id

         * in HBufC. HBufC's ownership is returned to caller.

         *

         * @since 3.0

         * @param aAttributeType The type of the attribute

         * @param aPresenceID The presenceID of the attribute

         * @return Attribute StoreId.

         */

        virtual HBufC* GenerateStoreIdL( TUint32 aAttributeType,

                                         const TDesC& aPresenceId ) const = 0;

        /**

         * Resolves attribute type and owner presence id

         * from store id.

         *

         * @since 3.0

         * @param aStoreId The store id to resolve.

         * @param aAttributeType On succesful return contains resolved attribute type.

         * @param aPresenceId On successful return contains resolved presence id.

         * Returned aPresenceId is valid only for the lifetime of given source store id.

         * @return KErrNone if succesful. KErrCorrupt if given aStoreId

         * isn't valid attribute store id.

         */

        virtual TInt ResolveStoreId( const TDesC& aStoreId,

                                     TUint32& aAttributeType,

                                     TPtrC& aPresenceId ) const = 0;

    public: // Batch operations

        /**

         * Stores an array of attribute models in a batch to storage.

         * Force stores the models, so edit locks are ignored.

         *

         * @since 3.0

         * @param aModel The models to store.

         */

        virtual void ForceStoreBatchL(

            const RPointerArray<MPEngPresenceAttrModel2> aModels ) = 0;

        /**

         * Removes an array of attribute models in a batch from storage.

         * Force removes the models, so edit locks are ignored.

         *

         * @since 3.0

         * @param aModel The models to remove from the storage.

         */

        virtual void ForceRemoveFromStoreBatchL(

            RPointerArray<MPEngPresenceAttrModel2> aModels ) = 0;

    protected:

        /**

         * Protected  destructor.

         *

         * Concrete Attribute Manager can't be

         * deleted through this interface.

         */

        virtual ~MPEngPresenceAttrManager() {};

    };

#endif      //  __MPENGPRESENCEATTRMANAGER_H

//  End of File