1 // Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // Interface class describing class that may contains user

    15 // data added to node

    16 //

    17 

    18 

    19 

    20 /**

    21  @file

    22  @publishedAll

    23  @released

    24 */

    25 #ifndef XMLENGUSERDATA_H

    26 #define XMLENGUSERDATA_H

    27 

    28 #include <e32def.h>

    29 

    30 /**

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

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

    33 data in a class that implements this interface.

    34 

    35 There are two common patterns for implementors of this interface:

    36 

    37 1)  Instance-based implementation

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

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

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

    41 may continue to hold the data.

    42 

    43 2)  Reference-counted implementation

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

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

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

    47 referring to this data.

    48 */

    49 class MXmlEngUserData {

    50 public:

    51     /**

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

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

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

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

    56     */

    57     virtual void Destroy() = 0;

    58     

    59     /**

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

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

    62 	implementor of this class.

    63     

    64     @return Pointer to a copy of this object.

    65 	@leave - One of the system-wide error codes

    66     */

    67     virtual MXmlEngUserData* CloneL() = 0;

    68 

    69 	/**

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

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

    72 	several types of MXmlEngUserData objects are used.

    73     

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

    75     */

    76     virtual void* ID() {return NULL;}

    77 };

    78 

    79 

    80 #endif /* XMLENGUSERDATA_H*/

    81