diff -r 000000000000 -r 2f259fa3e83a classicui_plat/avkon_testability_api/inc/TasDataModelInterface.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/classicui_plat/avkon_testability_api/inc/TasDataModelInterface.h Tue Feb 02 01:00:49 2010 +0200 @@ -0,0 +1,411 @@ +/* +* 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 +#include + +// 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 + +#endif // __TasDataModelInterface_H__ + +// End of File