// Copyright (c) 2005-2009 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:

// Interface class describing class that may contains user

// data added to node

//

/**

 @file

 @publishedAll

 @released

*/

#ifndef XMLENGUSERDATA_H

#define XMLENGUSERDATA_H

#include <e32def.h>

/**

Defines an interface so that user data can be stored in the DOM tree.

Applications that wish to store user data in the DOM tree must wrap the user

data in a class that implements this interface.

There are two common patterns for implementors of this interface:

1)  Instance-based implementation

The implementing class stores the user data.  The object can be duplicated with

CloneL() to form a new object that duplicates the user data.  When Destroy() is

called, the user data attached to the object is destroyed, but other duplicates

may continue to hold the data.

2)  Reference-counted implementation

The implementing class points to the user data.  The object can be duplicated,

but the user data is not duplicated.  When Destroy() is called, the object is

destroyed, but the user data is not destroyed unless this is the last object

referring to this data.

*/

class MXmlEngUserData {

public:

    /**

    Free memory that is allocated and do other case specific cleanup.  Whether

	this frees the user data depends on the implementation.  In a

	reference-counted implementation, the user data may only be destroyed

	when Destroy() is called on the last object referring to that data.

    */

    virtual void Destroy() = 0;

    /**

    Make a copy of the the object.  Whether this duplicates the data or

	creates a new object that points to the data is determined by the

	implementor of this class.

    @return Pointer to a copy of this object.

	@leave - One of the system-wide error codes

    */

    virtual MXmlEngUserData* CloneL() = 0;

	/**

	Gets the id of the object. It is up to the user data provider determine

	what the result is.  Such a "user data identification" may be useful if

	several types of MXmlEngUserData objects are used.

    @return Pointer that somehow identifies the type of MXmlEngUserData (NULL by default)

    */

    virtual void* ID() {return NULL;}

};

#endif /* XMLENGUSERDATA_H*/