/*
* Copyright (c) 2008 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: ECom plugin interface for testability data model for passing ui
* data from avkon to pc
*
*/
#ifndef __TASDATAMODELINTERFACE_H__
#define __TASDATAMODELINTERFACE_H__
// INCLUDES
#include <e32base.h>
#include <ecom/ecom.h>
// CONSTANTS
const static TUid KTasDataModelInterfaceUid = { 0x2001950D };
const static TUid KTasDataModelImplementationUid = { 0x2001950E };
// MACROS
// DATA TYPES
// FUNCTION PROTOTYPES
// FORWARD DECLARATIONS
class MTasObject;
// CLASS DECLARATION
/**
* Represents an attribute in tas data
* model. Attribute can have values or
* object as members.
*
* Attribute in the tas data model represents an attribute of an object.
* Attributes can be simple name value pairs or more complicated structures.
* Complicated attribute values are represented as tasobjects.
*
* The object does not have to contain all elements. Implementations of serialize
* have to take this fact into consideration.
*
*/
class MTasAttribute
{
public:
/**
* Set an id for the attribute. Used to identify objects.
*
* @param aName Name of the attribute.
*/
virtual void SetIdL( const TDesC& aId )=0;
/**
* Set an id for the attribute. Used to identify objects.
*
* @param aName Name of the attribute.
*/
virtual void SetIdL( const TInt& aId )=0;
/**
* Set the name of the attribute. A new copy of the given descriptor is made.
* The value is copied simply to avoid a scenario where the data model
* would remove a buffer which would still be needed by the calling
* component.
* @param aName Name of the attribute.
*/
virtual void SetNameL( const TDesC& aName )=0;
/**
* Set the type of the attribute. A new copy of the given descriptor is made.
* The value is copied simply to avoid a scenario where the data model
* would remove a buffer which would still be needed by the calling
* component.
*
* @param aType Type of the attribute.
*/
virtual void SetTypeL( const TDesC& aName )=0;
/**
* Add a simple value to the attribute. Simple values are
* can be repserented as string. If a more complicated
* value is required use AddObject.
* A new copy of the given descriptor is made.
* The value is copied simply to avoid a scenario where the data model
* would remove a buffer which would still be needed by the calling
* component.
*
* @param aValue New value for the attribute.
*/
virtual void AddValueL( const TDesC& aValue )=0;
/**
* Deep copy the data from the given attribute to this attribute.
*
* @param aAttribute Data from the given attribute will be deep
* copied into this attribute.
*/
virtual void CloneL( MTasAttribute &aAttribute )=0;
/**
* Destructor for MTasAttribute.
* Needs to be defined here in case some implementations use
* arrays to avoid user 42 panic.
*
*/
virtual ~MTasAttribute(){};
};
/**
* Represents an object in tas data model. MTasObjects are derived from MTasAttribute.
* MTasObject can contains a handle to its parent, children and derivation tree.
*
* The object does not have to contain all elements. Implementations of serialize
* have to take this fact into consideration.
*
*/
class MTasObject : public MTasAttribute
{
public:
/**
* Add new attribute to the MTasObject.
* A reference to a new empty MTasAttribute instance is returned.
*
* @return Reference to a new MTasAttribute.
*/
virtual MTasAttribute& AddAttributeL()=0;
/**
* Add new attribute to the MTasObject.
* A reference to a new empty MTasAttribute instance is returned.
*
* @param aName Name of the attribute.
* @param aValue Value of the attribute.
*
* @return Reference to a new MTasAttribute.
*/
virtual MTasAttribute& AddAttributeL( const TDesC& aName, const TDesC& aValue)=0;
/**
* Add new attribute to the MTasObject.
* A reference to a new empty MTasAttribute instance is returned.
*
* @param aName Name of the attribute.
* @param aValue Value of the attribute.
*
* @return Reference to a new MTasAttribute.
*/
virtual MTasAttribute& AddAttributeL( const TDesC& aName, const TInt& aValue)=0;
/**
* Set the parent of this object. Parent is not the object that this object derives
* from but an object that this object belongs to e.g ui component in a window.
*
* The parent will be added to model as a deep copy of the given object. This is done to make
* sure that the parent object which may also reside in a different location in the model
* is not deleted too early by some party. This means that the parent given will not be deleted
* by this model.
*
* @param aParent Parent of this object.
*/
virtual void SetParentL( MTasObject& aParent )=0;
/**
* Add a complicated value to the object.
* Returns a reference new empty MTasObject which has been
* added to the attribute.
*
* @return A reference to a new empty MTasObject instance.
*/
virtual MTasObject& AddObjectL( )=0;
/**
* Add the object that this object derives from.
* A reference to a new MTasObject instance is retuned.
*
* @return A reference to a new MTasObject instance.
*/
virtual MTasObject& AddSuperClassL()=0;
/**
* Deep copy the data from the given object to this object.
*
* @param aObject Data from the given object will be deep
* copied into this object.
*/
virtual void CloneL( MTasObject& aObject)=0;
/**
* Destructor for MTasObject
* Needs to be defined here in case some implementations use
* arrays to avoid user 42 panic.
*
*/
virtual ~MTasObject(){};
};
/**
* The container can represent an application for instance that contains
* the objects.
*
*/
class MTasObjectContainer
{
public:
/**
* Set an id for the attribute. Used to identify objects.
*
* @param aName Name of the attribute.
*/
virtual void SetIdL( const TDesC& aId )=0;
/**
* Set the name of the attribute. A new copy of the given descriptor is made.
* The value is copied simply to avoid a scenario where the data model
* would remove a buffer which would still be needed by the calling
* component.
* @param aName Name of the attribute.
*/
virtual void SetNameL( const TDesC& aName )=0;
/**
* Set the type of the attribute. A new copy of the given descriptor is made.
* The value is copied simply to avoid a scenario where the data model
* would remove a buffer which would still be needed by the calling
* component.
*
* @param aType Type of the attribute.
*/
virtual void SetTypeL( const TDesC& aName )=0;
/**
* Add new object to the container.
*
* @return New MTasObject added to the storage.
*/
virtual MTasObject& AddNewObjectL()=0;
/**
* Add new object to the container.
* The container can represent an application for instance that contains
* the objects.
*
* @param aName Name of the object.
* @param aValue Value of the object.
* @return New MTasObject added to the storage.
*/
virtual MTasObject& AddNewObjectL( const TDesC& aName, const TDesC& aType, const TDesC& aId )=0;
/**
* Deep copy the data from the given container to this container.
*
* @param aContainer Data from the given container will be deep
* copied into this container.
*/
virtual void CloneL( MTasObjectContainer& aContainer )=0;
/**
* Destructor for MTasObjectContainer
* Needs to be defined here in case some implementations use
* arrays to avoid user 42 panic.
*
*/
virtual ~MTasObjectContainer(){};
};
/**
* Interface to the TasDataModel. The tas data model contains the ui data collected
* From avkon. The data format and internal data model implementation are the responsibility of
* intarface implementations.
*
* Some implementation considerations:
* All attributes of MTasAttribute and MTasObject are optional. This means that serialize
* implementations must take this fact into consideration.
* The model must be responsible for freeing all memory it has reserved.
* The buffer passed to the SerializeTasDataL is naturally the responsibility
* of the caller.
*/
class CTasDataModelInterface : public CBase
{
public:
/**
* Symbian constructor
*/
static CTasDataModelInterface* NewL();
/**
* Wraps ECom object instantitation
* plug-in loaded by its UID
*
* @param aUID service plugin implementation UDI
*/
static CTasDataModelInterface* NewL(const TUid aUID);
/**
* Wraps ECom object instantitation
* default resovler is used
*
* @param aMatchString service plugin name
*/
static CTasDataModelInterface* NewL(const TDesC8& aMatchString);
/**
* Destructor
*/
virtual ~CTasDataModelInterface();
public: //Comm plugin interface methods
/**
* Add new Object to the data model.
* Objects added directly to the DataModel
* will be serialized to the top level.
*
* @return A reference to a new TasObject, which will be added to the data model.
*/
virtual MTasObjectContainer& AddNewObjectContainerL() = 0;
/**
* Clean and destroy the added objects from the data model.
*
*/
virtual void CleanObjectData() = 0;
/**
* Make a deep copy of the given CTasDataModelInterface
* object to this CTasDataModelInterface object.
* Any existing data will be removed berofe the clone is performed.
* For merging models use MergeL.
* All data is copied so the original model can be destroyed
* freely after the clone.
*
* @param aModel CTasDataModelInterface to be copied into this object.
*/
virtual void CloneL( CTasDataModelInterface& aModel )=0;
/**
* Merges two TasDataModel structures into one model.
* Merging is done by appending the TasObjectContainers
* from the given model to this model. Merged data is copied
* so that the given model can be deleted with no affect to this
* instance.
*
* @param aModel CTasDataModelInterface to be merged to this object.
*/
virtual void MergeL( CTasDataModelInterface& aModel )=0;
/**
* Serialize the datamodel structure into the given buffer.
*
* Implementing classes must consider the following facts when implementing:
* All variables in MTasObject and MTasAttribute are optional. Existence of
* data can not be assumed.
* All memory reserved by the model is to be removed once model deleted.
* aDataBuffer is considered not part of the model so its is the responsibility
* of the calling module.
*
* @param The target buffer to where to serialize the data model.
* @return Amount of bytes updated to the buffer.
*/
virtual TInt SerializeTasDataL(
RBuf8& aDataBuffer,
TBool aCompressionOn = EFalse ) = 0;
/**
* Serialize the datamodel structure into a file.
*
* Implementing classes must consider the following facts when implementing:
* All variables in MTasObject and MTasAttribute are optional. Existence of
* data can not be assumed.
*
*
* @param The target buffer to where to serialize the data model.
* @return Number of byte written
*/
virtual TInt SerializeTasDataL(
RFs& aRFs,
const TDesC& aFileName,
TBool aCompressionOn = EFalse ) = 0;
private: // Data
/// Current instance identifier
TUid iImplementation;
};
#include <TasDataModelInterface.inl>
#endif // __TasDataModelInterface_H__
// End of File