1 /* |
1 // Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies). |
2 * Copyright (c) 2004-2005 Nokia Corporation and/or its subsidiary(-ies). |
2 // All rights reserved. |
3 * All rights reserved. |
3 // This component and the accompanying materials are made available |
4 * This component and the accompanying materials are made available |
4 // under the terms of "Eclipse Public License v1.0" |
5 * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members |
5 // which accompanies this distribution, and is available |
6 * which accompanies this distribution, and is available |
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
7 // |
8 * |
8 // Initial Contributors: |
9 * Initial Contributors: |
9 // Nokia Corporation - initial contribution. |
10 * Nokia Corporation - initial contribution. |
10 // |
11 * |
11 // Contributors: |
12 * Contributors: |
12 // |
13 * |
13 // Description: |
14 * Description: Interface class describing class that may contains user |
14 // Interface class describing class that may contains user |
15 * data aded to node |
15 // data added to node |
16 * |
16 // |
17 */ |
|
18 |
17 |
19 |
18 |
20 |
19 |
21 |
20 /** |
22 |
21 @file |
23 |
22 @publishedAll |
24 |
23 @released |
25 #ifndef XMLENGINE_USERDATA_H_INCLUDED |
24 */ |
26 #define XMLENGINE_USERDATA_H_INCLUDED |
25 #ifndef XMLENGUSERDATA_H |
|
26 #define XMLENGUSERDATA_H |
27 |
27 |
28 #include <e32def.h> |
28 #include <e32def.h> |
29 |
29 |
30 /** |
30 /** |
31 * MXmlEngUserData is an abstract base class (interface) for user data that can be |
31 Defines an interface so that user data can be stored in the DOM tree. |
32 * stored in the DOM tree. Applications that wish to store user data in the |
32 Applications that wish to store user data in the DOM tree must wrap the user |
33 * DOM tree must wrap the user data in a class that implemens this interface. |
33 data in a class that implements this interface. |
34 * |
34 |
35 * @lib XmlEngineDOM.lib |
35 There are two common patterns for implementors of this interface: |
36 * @since S60 v3.1 |
36 |
37 */ |
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 */ |
38 class MXmlEngUserData { |
49 class MXmlEngUserData { |
39 public: |
50 public: |
40 /** |
51 /** |
41 * Free memory that is allocated and do other case specific cleanup. |
52 Free memory that is allocated and do other case specific cleanup. Whether |
42 * |
53 this frees the user data depends on the implementation. In a |
43 * @since S60 v3.1 |
54 reference-counted implementation, the user data may only be destroyed |
44 */ |
55 when Destroy() is called on the last object referring to that data. |
|
56 */ |
45 virtual void Destroy() = 0; |
57 virtual void Destroy() = 0; |
46 |
58 |
47 /** |
59 /** |
48 * Make a copy of the the object. Note that if reference counting is used or |
60 Make a copy of the the object. Whether this duplicates the data or |
49 * the same pointer can be safely copied to other places the implementation |
61 creates a new object that points to the data is determined by the |
50 * of this method may just return a pointer to self. |
62 implementor of this class. |
51 * |
63 |
52 * Copying user data when copying nodes has not been implemented |
64 @return Pointer to a copy of this object. |
53 * so this method is for future use (though there's no harm in implementing |
65 @leave - One of the system-wide error codes |
54 * it, of course). |
66 */ |
55 * |
|
56 * @since S60 v3.1 |
|
57 * @return Pointer to a copy of this object. |
|
58 */ |
|
59 virtual MXmlEngUserData* CloneL() = 0; |
67 virtual MXmlEngUserData* CloneL() = 0; |
60 |
68 |
61 /** |
69 /** |
62 * Get id of the object. It is up to user-data provider what the result is. |
70 Gets the id of the object. It is up to the user data provider determine |
63 * Such a "user data identification" may be in use if several types of |
71 what the result is. Such a "user data identification" may be useful if |
64 * MXmlEngUserData objects are used. |
72 several types of MXmlEngUserData objects are used. |
65 * |
73 |
66 * @since S60 v3.1 |
74 @return Pointer that somehow identifies the type of MXmlEngUserData (NULL by default) |
67 * @return Pointer that somehow identifies the type of MXmlEngUserData (NULL by default) |
75 */ |
68 */ |
|
69 virtual void* ID() {return NULL;} |
76 virtual void* ID() {return NULL;} |
70 }; |
77 }; |
71 |
78 |
72 |
79 |
|
80 #endif /* XMLENGUSERDATA_H*/ |
73 |
81 |
74 #endif /* XMLENGINE_USERDATA_H_INCLUDED*/ |
|