|
1 // Copyright (c) 2001-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 // This file contains the declaration of the CMDXMLElement class. |
|
15 // |
|
16 // |
|
17 |
|
18 /** |
|
19 @file |
|
20 */ |
|
21 |
|
22 #ifndef __GMXMLELEMENT_H__ |
|
23 #define __GMXMLELEMENT_H__ |
|
24 |
|
25 #include <e32base.h> |
|
26 #include <badesca.h> |
|
27 #include <gmxmlnode.h> |
|
28 |
|
29 |
|
30 // forward references |
|
31 class CMDXMLEntityConverter; |
|
32 class CMDXMLComposer; |
|
33 |
|
34 |
|
35 // Constants for the initial and terminal states |
|
36 const TInt KXMLMinJump = 5; // Don't do binary chop below this size. Not a critical value. |
|
37 |
|
38 class CMDXMLElement : public CMDXMLNode |
|
39 /** Generic XML element, and base class for particular XML element types. |
|
40 |
|
41 It provides access to the element tag name and its attribute list. Attributes are |
|
42 stored as name-value pairs. |
|
43 @publishedPartner |
|
44 @released |
|
45 */ |
|
46 { |
|
47 public: |
|
48 /** Allocates and constructs a new CMDXMLElement, leaving the object on the cleanup |
|
49 stack. |
|
50 |
|
51 @param aCanHaveChildren Set to true if the element can have children |
|
52 @param aOwnerDocument Pointer to the document at the root of the DOM tree |
|
53 @param aTagName Name of the tag for the element |
|
54 @leave KErrNoMemory Out of memory |
|
55 @return The new CMDXMLElement */ |
|
56 IMPORT_C static CMDXMLElement* NewLC( TBool aCanHaveChildren, CMDXMLDocument* aOwnerDocument, TPtrC aTagName ); |
|
57 |
|
58 /** Allocates and constructs a new CMDXMLElement. |
|
59 |
|
60 @param aCanHaveChildren Set to true if the element can have children |
|
61 @param aOwnerDocument Pointer to the document at the root of the DOM tree |
|
62 @param aTagName Name of the tag for the element |
|
63 @leave KErrNoMemory Out of memory |
|
64 @return The new CMDXMLElement */ |
|
65 IMPORT_C static CMDXMLElement* NewL( TBool aCanHaveChildren, CMDXMLDocument* aOwnerDocument, TPtrC aTagName ); |
|
66 |
|
67 /** Destructor. */ |
|
68 IMPORT_C virtual ~CMDXMLElement(); |
|
69 |
|
70 // Attribute handling routines. |
|
71 |
|
72 /** Gets a specified attribute value. |
|
73 |
|
74 @param aAttributeName Name of the attribute to get |
|
75 @param aAttributeValue On return, the value of the attribute |
|
76 @return KErrNone if successful, KErrNotFound if the named attribute is not set. */ |
|
77 IMPORT_C virtual TInt GetAttribute(const TDesC& aAttributeName, TPtrC& aAttributeValue ) const; |
|
78 |
|
79 /** Checks the validity of an attribute and adds it to the DOM if it's valid. |
|
80 |
|
81 @param aAttributeName Name of the attribute to set |
|
82 @param aAttributeValue Value of the attribute |
|
83 @leave KErrNoMemory Out of memory |
|
84 @return KErrNone if successful, KErrNotSupported if an invalid attribute name |
|
85 or attribute value. */ |
|
86 IMPORT_C virtual TInt SetAttributeL(const TDesC& aAttributeName, const TDesC& aAttributeValue); |
|
87 |
|
88 /** Checks the validity of an attribute and adds it to the DOM. The aStoreInvalid |
|
89 parameter is used to control whether invalid attributes are added to the DOM. |
|
90 @param aAttributeName Name of the attribute to set |
|
91 @param aAttributeValue Value of the attribute |
|
92 @param aStoreInvalid If set to EFalse only attributes that are found to be valid will be added to |
|
93 the DOM. Set to ETrue to store all attributes in the DOM, even those that are invalid. |
|
94 @leave KErrNoMemory Out of memory |
|
95 @return KErrNone if successful, KErrNotSupported if an invalid attribute name |
|
96 or attribute value. */ |
|
97 IMPORT_C TInt SetAttributeL(const TDesC& aAttributeName, const TDesC& aAttributeValue, TBool aStoreInvalid); |
|
98 |
|
99 /** Removes a specified attribute. |
|
100 |
|
101 @param aAttributeName Name of the attribute to remove |
|
102 @return KErrNone if successful, KErrNotFound if the named attribute is not |
|
103 present. */ |
|
104 IMPORT_C virtual TInt RemoveAttribute(const TDesC& aAttributeName); |
|
105 |
|
106 /** Tests if a specified attribute is set. |
|
107 |
|
108 @param aAttributeName Name of the attribute to test |
|
109 @return True if the named attribute has a value set, false if not */ |
|
110 IMPORT_C virtual TBool IsAttributeSpecified(const TDesC& aAttributeName) const; |
|
111 |
|
112 |
|
113 /** Checks the children of this node for validity. |
|
114 |
|
115 It checks that the list of child elements conforms to those allowed by the DTD. |
|
116 |
|
117 In a generic CMDXMLElement object, this is always true as it has no basis |
|
118 for a meaningful check. As well as checking the list of direct children, it |
|
119 calls CheckChildren() for each child element. It does not check child nodes |
|
120 that are not elements, as they cannot have children. |
|
121 |
|
122 @return True if the node has valid children */ |
|
123 IMPORT_C virtual TBool CheckChildren(); |
|
124 |
|
125 // maybe these should be node functions ? |
|
126 /** Gets a pointer to the first child of a given type if any, otherwise returns |
|
127 NULL. |
|
128 |
|
129 @param aElementType Name of element type to return |
|
130 @return First child element */ |
|
131 IMPORT_C CMDXMLElement* FirstChildOfType(const TDesC& aElementType); |
|
132 |
|
133 /** Gets a pointer to the last child of a given type if any, otherwise returns |
|
134 NULL. |
|
135 |
|
136 @param aElementType Name of element type to return |
|
137 @return Last child element */ |
|
138 IMPORT_C CMDXMLElement* LastChildOfType(const TDesC& aElementType); |
|
139 |
|
140 |
|
141 |
|
142 protected: //construction |
|
143 /** |
|
144 * Constructor |
|
145 * @param aCanHaveChildren Flag to indicate if the node represents a node which is allowed children |
|
146 * @param aOwnerDocument Pointer to the document at the root of the DOM tree - if NULL then assume this is the root |
|
147 */ |
|
148 IMPORT_C CMDXMLElement( TBool aCanHaveChildren, CMDXMLDocument* aOwnerDocument ); |
|
149 |
|
150 void ConstructL(); |
|
151 protected: |
|
152 /** |
|
153 * Check the immediate children of this element - i.e. the first level of children only |
|
154 * The default implementation returns true - derived classes can override with |
|
155 * DTD-specific checks. |
|
156 * @return True if immediate children are valid |
|
157 */ |
|
158 IMPORT_C virtual TBool CheckImmediateChildren(); |
|
159 |
|
160 private: |
|
161 TBool DoCheckImmediateChildrenL(); |
|
162 |
|
163 |
|
164 public: |
|
165 /** Finds an attribute and returns the index of it. |
|
166 |
|
167 @param aAttName The attribute to search for |
|
168 @return The index of the attribute if found, or KErrNotFound */ |
|
169 IMPORT_C TInt FindIndex(const TDesC &aAttName); |
|
170 |
|
171 |
|
172 /** Gets the name and value of an attribute at a given index. |
|
173 |
|
174 @param Index The array index of the element for which details are required |
|
175 @param aAttributeName The attribute name returned |
|
176 @param aAttributeValue The attribute value returned |
|
177 @return KErrNone if index is valid, else KErrNotFound */ |
|
178 IMPORT_C TInt AttributeDetails(TInt Index, TPtrC& aAttributeName, TPtrC& aAttributeValue); |
|
179 |
|
180 /** Gets the number of attributes that this element has. |
|
181 |
|
182 @return The number of attributes held by the element */ |
|
183 IMPORT_C TInt NumAttributes(); |
|
184 |
|
185 protected: |
|
186 /** Store attribute names */ |
|
187 CDesCArraySeg* iDescAttName; // Store Attribute Names |
|
188 /** Store attribute values */ |
|
189 CDesCArraySeg* iDescAttValue; // Store Attribute Values |
|
190 |
|
191 }; |
|
192 |
|
193 |
|
194 #endif |