|
1 /* |
|
2 * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: |
|
15 * |
|
16 */ |
|
17 |
|
18 /** @file |
|
19 @publishedAll |
|
20 @released |
|
21 */ |
|
22 #ifndef XMLENGELEMENT_H |
|
23 #define XMLENGELEMENT_H |
|
24 |
|
25 #include <xml/dom/xmlengattr.h> |
|
26 #include <xml/dom/xmlengnamespace.h> |
|
27 |
|
28 template<class T> class RXmlEngNodeList; |
|
29 |
|
30 |
|
31 /** |
|
32 This class represents an XML element in the DOM tree. |
|
33 |
|
34 Namespace handling: |
|
35 |
|
36 The namespace of a XML element is an URI that in pair with the local part of |
|
37 the element's name consistute the @c expanded-name of the element. It is said |
|
38 that "the element is of NNN namespace". |
|
39 |
|
40 XML elements are shown as belonging to a specific namespace by using prefixes |
|
41 that previously were bound to some namespace URIs. The scope of a prefix is the |
|
42 element, where it was declared and all its child (sub-)elements. |
|
43 |
|
44 Namespace declaration is created by using a special @c xmlns:{prefix-name} |
|
45 attribute (which is not really considered as an attribute in DOM): |
|
46 @code |
|
47 <a xmlns:pr="http://some.uri.com/"> ... </a> |
|
48 OR |
|
49 <pr:a xmlns:pr="http://some.uri.com/"> ... </a> |
|
50 <a xmlns="http://some.uri.com/"> ... </a> |
|
51 @endcode |
|
52 |
|
53 The latter two examples are equivalent and show the use of @c default namespace. |
|
54 |
|
55 Implementation notes: |
|
56 - Elements having no namespace are either presented with a NULL |
|
57 TXmlEngNamespace node or a TXmlEngNamespace node that has NULL (KNullDesC8) |
|
58 prefix and namespace URI set to "" (an empty descriptor). The former is |
|
59 used by default on all nodes, whereas the latter is for cases when some node |
|
60 contains undeclaration of the default namespace: |
|
61 @code |
|
62 <a xmlns=""> .. </a> |
|
63 @endcode |
|
64 |
|
65 - The prefix of the default attribute is NULL (KNullDesC8), not an "" (empty |
|
66 descriptor). An empty descriptor which corresponds to |
|
67 @code |
|
68 <a xmlns:="http://some.uri.com/"> ... </a> |
|
69 @endcode |
|
70 (it does not contradict XML spec, but you are strongly advised against using |
|
71 this) |
|
72 |
|
73 - Prefix "xml" is reserved by XML Namespace spec for special purposes; it is |
|
74 implicitly bound to XML's namespace <i>"http://www.w3.org/XML/1998/namespace"</i> |
|
75 and no one is allowed to use this prefix except as with spec-defined |
|
76 elements and attributes or to rebind this prefix to other namespaces |
|
77 |
|
78 - Namespace URI may be "" (an empty descriptor) only for default namespace. In |
|
79 other words, "" namespace URI may not be bound to non-NULL prefix. |
|
80 |
|
81 Declaration of "" (an empty descriptor) namespace with NULL (KNullDesC8) |
|
82 prefix results in: |
|
83 @code |
|
84 <a xmlns=""> ... </a> |
|
85 @endcode |
|
86 which undeclares any existing (in some parent element) default namespace |
|
87 for the scope of element 'a': element, its attributes and all child nodes |
|
88 of DOM tree. Note, that such "undeclaration" will be added only if neccessary. |
|
89 |
|
90 - Unneccessary namespace declaration are ignored. Attemps to add namespace binding |
|
91 using same namespace URI and prefix if such binding already exists in the scope |
|
92 will have no effect. |
|
93 |
|
94 - IMPORTANT! Attributes DO NOT HAVE default namespaces. If an attribute has no |
|
95 prefix, its namespace is undeclared even if there is some default namespaces for |
|
96 the scope of the element, which contains the attribute. |
|
97 |
|
98 So, it is wrong to write something like this: |
|
99 @code |
|
100 <a xmlns="ns_uri" attr="value"> ... </a> |
|
101 @endcode |
|
102 and assume that the attr belongs to namespace pointed to with @c ns_uri. |
|
103 |
|
104 HINTS: |
|
105 - Use namespace declaration nodes as much as possible (but watch out for prefix collisions). |
|
106 - Add most referred to namespace declarations (AddNamespaceDeclarationL(uri,pref)) after |
|
107 any other namespace declarations in a element -- they will be found faster in |
|
108 namespace lookups. |
|
109 |
|
110 For more informarion on NULL and NULL nodes: |
|
111 @see TXmlEngNode |
|
112 @see KNullDesC8 |
|
113 */ |
|
114 class TXmlEngElement : public TXmlEngNode |
|
115 { |
|
116 public: |
|
117 /** Default constructor */ |
|
118 inline TXmlEngElement(); |
|
119 |
|
120 /** |
|
121 Constructor |
|
122 @param aInternal element pointer |
|
123 */ |
|
124 inline TXmlEngElement(void* aInternal); |
|
125 |
|
126 /* |
|
127 Extensions to the DOM Level 3 Core methods |
|
128 */ |
|
129 |
|
130 /** |
|
131 Retrieves a list of the attribute nodes of an element |
|
132 |
|
133 Upon return, aList is initialized and is ready for use with HasNext() and |
|
134 Next() methods: |
|
135 |
|
136 @code |
|
137 ... |
|
138 TXmlEngElement root = doc.DocumentElement(); |
|
139 RXmlEngNodeList<TXmlEngAttr> attlist; |
|
140 root.GetAttributes(attlist); |
|
141 while (attlist.HasNext()) |
|
142 processAttribute(attlist.Next()); |
|
143 ... |
|
144 attlist.Close(); |
|
145 @endcode |
|
146 |
|
147 If there are no attributes the list will be empty. |
|
148 |
|
149 @param aList An attribute list to initialize |
|
150 */ |
|
151 IMPORT_C void GetAttributes(RXmlEngNodeList<TXmlEngAttr>& aList) const; |
|
152 |
|
153 /** |
|
154 Retrieves a list of child elements of an element. |
|
155 |
|
156 Upon return, aList is initialized and is ready for use with HasNext() and |
|
157 Next() methods. |
|
158 |
|
159 Note: This returns a list of the child element nodes only. |
|
160 |
|
161 There is no affect if the element attributes are empty. |
|
162 |
|
163 @param aList A child list to initialize |
|
164 */ |
|
165 IMPORT_C void GetChildElements(RXmlEngNodeList<TXmlEngElement>& aList) const; |
|
166 |
|
167 /** |
|
168 Creates a new attribute node outside of any namespace (i.e. it has no |
|
169 prefix), sets the attribute's value and links it as the last attribute of |
|
170 the current element. |
|
171 |
|
172 Note: |
|
173 - No checks are made that an attribute with the same name exists. |
|
174 Use this method only on newly created elements! |
|
175 Otherwise, use TXmlEngElement::SetAttributeL() |
|
176 - Attributes do not inherit default namespace of its element |
|
177 (http://w3.org/TR/REC-xml-names/#defaulting) |
|
178 - The attribute's value is the second argument in all AddNewAttributeL() methods |
|
179 |
|
180 When adding the first attribute, use TXmlEngNode::SetAsFirstSibling() on the attribute: |
|
181 @code |
|
182 TXmlEngElement el = ... ; // get some element |
|
183 el.AddNewAttributeL("version","0.1").SetAsFirstSibling(); |
|
184 @endcode |
|
185 |
|
186 Copies are taken of descripters passed in. |
|
187 |
|
188 @see SetAsLastSibling() |
|
189 @see MoveBeforeSibling(TXmlEngNode) |
|
190 @see MoveAfterSibling(TXmlEngNode) |
|
191 * |
|
192 @param aName A local name of the attribute |
|
193 @param aValue Value to set for new attribute or KNullDesC8 |
|
194 @return The created attribute |
|
195 @leave KXmlEngErrNullNode The node is NULL |
|
196 @leave KXmlEngErrWrongUseOfAPI aName is empty |
|
197 @leave - One of the system-wide error codes |
|
198 */ |
|
199 IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName, const TDesC8& aValue); |
|
200 |
|
201 /** |
|
202 Creates a new attribute node and adds it to the element. |
|
203 |
|
204 The provided namespace declaration is used to set the attribute's namespace. |
|
205 |
|
206 Note: If aNsDef is not defined in some of the attribute's ascendants |
|
207 (including this element), then the ReconcileNamespacesL() method must be |
|
208 called on this element later. |
|
209 |
|
210 Copies are taken of descripters passed in. |
|
211 |
|
212 @param aName The local name of attribute |
|
213 @param aValue Value to set for new attribute or KNullDesC8 |
|
214 @param aNsDef Namespace to add to the attribute |
|
215 @return The created attribute |
|
216 @leave KXmlEngErrNullNode The node is NULL |
|
217 @leave KXmlEngErrWrongUseOfAPI aName is empty |
|
218 @leave - One of the system-wide error codes |
|
219 */ |
|
220 IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName, |
|
221 const TDesC8& aValue, |
|
222 const TXmlEngNamespace aNsDef); |
|
223 |
|
224 /** |
|
225 Creates a new attribute for the element. A namespace declaration for the |
|
226 attribute namespace is also created. |
|
227 |
|
228 Note: Namespace declarations are reused if possible (no redundant ones are |
|
229 created) |
|
230 |
|
231 Copies are taken of descripters passed in. |
|
232 |
|
233 @param aName The local name of attribute |
|
234 @param aValue Value to set for the new attribute or an empty string |
|
235 @param aNsUri Namespace URI |
|
236 @param aPrefix Namespace prefix |
|
237 @return The created attribute |
|
238 @leave KXmlEngErrNullNode The node is NULL |
|
239 @leave KXmlEngErrWrongUseOfAPI aName is empty |
|
240 @leave - One of the system-wide error codes |
|
241 */ |
|
242 IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName, |
|
243 const TDesC8& aValue, |
|
244 const TDesC8& aNsUri, |
|
245 const TDesC8& aPrefix); |
|
246 |
|
247 /** |
|
248 Creates a new attribute node using the namespace of its parent element |
|
249 (this element), sets the attribute's value and links it as the last |
|
250 attribute of the element |
|
251 |
|
252 For more hints how to use it @see AddNewAttributeL(const TDesC8&,const TDesC8&) |
|
253 |
|
254 Note: |
|
255 - No checks are made that an attribute with the same name exists |
|
256 - if the namespace of the parent element is default (i.e. bound prefix is KNullDesC8), |
|
257 then a temporary prefix will be used and bound to the same namespace URI as the element |
|
258 (It is due to the fact that default namespaces do not spread on unprefixed attributes, |
|
259 see http://w3.org/TR/REC-xml-names/#defaulting) |
|
260 |
|
261 Copies are taken of descripters passed in. |
|
262 @see KNullDesC8 |
|
263 |
|
264 @param aName Local name of attribute |
|
265 @param aValue Value to set for the new attribute or empty. |
|
266 @return The created attribute |
|
267 @leave KXmlEngErrNullNode The node is NULL |
|
268 @leave KXmlEngErrWrongUseOfAPI aName is empty |
|
269 @leave - One of the system-wide error codes |
|
270 */ |
|
271 inline TXmlEngAttr AddNewAttributeSameNsL(const TDesC8& aName, const TDesC8& aValue); |
|
272 |
|
273 /** |
|
274 Creates a new attribute using the namespace which is bound to the specified prefix |
|
275 |
|
276 Use this mothod only for construction of new parts of DOM tree where |
|
277 you know for sure that the prefix is bound in the given scope. |
|
278 @code |
|
279 TXmlEngElement el = parent.AddNewAttributeUsePrefixL("property","ObjName","rdf"); |
|
280 el.AddNewAttributeUsePrefixL("type", "xs:integer", "rdf"); |
|
281 @endcode |
|
282 |
|
283 Otherwise, you should check that the prefix is bound like this example shows: |
|
284 @code |
|
285 TXmlEngNamespace boundNS = TXmlEngNamespace::LookupByPrefix(thisElement, prefix); |
|
286 if (boundNS.NotNull()){ |
|
287 thisElement.AddNewAttributeUsePrefixL("name", value, prefix); |
|
288 } |
|
289 @endcode |
|
290 |
|
291 Note: Use AddNewAttributeNsL(name,value,nsDefNode) as much as you can, |
|
292 because it is the most efficient way to create namespaced DOM elements (no |
|
293 additional lookups for namespace declarations are required). |
|
294 |
|
295 @code |
|
296 // If namespace with given URI is not in the scope, then it will be declared |
|
297 // and bound to "data" prefix. |
|
298 TXmlEngNamespace nsDef = elem.FindOrCreateNsDefL("http://../Data", "data"); |
|
299 elem.AddNewAttributeL("location", "...", nsDef); |
|
300 elem.AddNewElementL("child", nsDef).AddNewAttributeL("attr","...value..."); |
|
301 // the result is |
|
302 ... |
|
303 <elem xmlns:data="http://../Data" data:location="..."> |
|
304 <data:child attr="...value..."/> |
|
305 </elem> |
|
306 ... |
|
307 // |
|
308 @endcode |
|
309 |
|
310 Copies are taken of descripters passed in. |
|
311 |
|
312 @param aLocalName The local name of the attribute |
|
313 @param aValue Value to set for the new attribute or empty string. |
|
314 @param aPrefix Namespace prefix for the new attribute |
|
315 @return The created attribute |
|
316 @leave KXmlEngErrNullNode The node is NULL |
|
317 @leave KXmlEngErrWrongUseOfAPI aLocalName is empty |
|
318 @leave KErrNoMemory The namespace is not found and the URI is not |
|
319 http://www.w3.org/XML/1998/namespace; or there is a memory allocation error |
|
320 @leave - One of the system-wide error codes |
|
321 */ |
|
322 IMPORT_C TXmlEngAttr AddNewAttributeUsePrefixL(const TDesC8& aLocalName, |
|
323 const TDesC8& aValue, |
|
324 const TDesC8& aPrefix); |
|
325 |
|
326 /** |
|
327 Creates new attributes using the namespace in scope, which has the specified URI |
|
328 |
|
329 Almost the same as AddNewAttributeUsePrefixL() but does lookup by namespace URI |
|
330 |
|
331 @see AddNewAttributeUsePrefixL(const TDesC8&,const TDesC8&,const TDesC8&) |
|
332 |
|
333 Copies are taken of descripters passed in. |
|
334 @see KNullDesC8 |
|
335 |
|
336 @param aLocalName The local name of the attribute |
|
337 @param aValue Value to set for new attribute or empty string. |
|
338 @param aNsUri Namespace URI for new attribute |
|
339 @return NULL attribute if namespace declaration is not found OR newly added |
|
340 to the end of attribute list attribute of this element. |
|
341 @leave KXmlEngErrNullNode The node is NULL |
|
342 @leave KXmlEngErrWrongUseOfAPI aLocalName is empty |
|
343 @leave - One of the system-wide error codes |
|
344 */ |
|
345 IMPORT_C TXmlEngAttr AddNewAttributeWithNsL(const TDesC8& aLocalName, |
|
346 const TDesC8& aValue, |
|
347 const TDesC8& aNsUri); |
|
348 |
|
349 /** |
|
350 Adds attribute to element that will be used as Xml:Id. Does not check if |
|
351 an attribute with the same name exists. |
|
352 |
|
353 Note: Call RXmlEngDocument.RegisterXmlIdL(aName,aNsUri) first to register |
|
354 existed id's in the document. If the ids are not registered the ID will |
|
355 not be added to the element. |
|
356 |
|
357 Copies are taken of descripters passed in. |
|
358 |
|
359 @param aLocalName Name of the attribute |
|
360 @param aValue Value of the attribute |
|
361 @param aNs Namespace of the attribute |
|
362 @return Attribute if created. Null attribute if Xml:Id exists |
|
363 @leave KXmlEngErrWrongUseOfAPI Element is NULL or attribute doesn't exist |
|
364 @leave - One of the system-wide error codes |
|
365 */ |
|
366 IMPORT_C TXmlEngAttr AddXmlIdL(const TDesC8& aLocalName, |
|
367 const TDesC8& aValue, |
|
368 TXmlEngNamespace aNs = TXmlEngNamespace()); |
|
369 |
|
370 /** |
|
371 Adds a child element with no namespace. This results in adding an element |
|
372 with aName and no prefix. |
|
373 |
|
374 This method is the best for creation of non-namespace based documents |
|
375 or document fragments, where no default namespace declared. |
|
376 |
|
377 It may be used also as a method for adding elements from the default |
|
378 namespace, BUT namespace will be assigned ONLY after serialization of the |
|
379 current document and parsing it back into a DOM tree!! If you need the new |
|
380 element to inherit the default namespace use: |
|
381 |
|
382 @code |
|
383 ... |
|
384 TXmlEngNamespace defns = element.DefaultNamespace(); |
|
385 TXmlEngElement newEl = element.AddNewElementL("Name",defns); |
|
386 ... |
|
387 @endcode |
|
388 |
|
389 It is not recommended that you use an undefined namespace with libxml. |
|
390 If an undefined namespace for the element is truly required, then DO NOT |
|
391 USE this method if there is a default namespace in the scope! |
|
392 @see AddNamespaceDeclarationL |
|
393 |
|
394 Copies are taken of descripters passed in. |
|
395 |
|
396 @param aName The name of the element |
|
397 @return The created element |
|
398 @leave KXmlEngErrNullNode Element is NULL |
|
399 @leave KXmlEngErrWrongUseOfAPI Name is not specified |
|
400 @leave - One of the system-wide error codes |
|
401 */ |
|
402 IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aName); |
|
403 |
|
404 /** |
|
405 Creates a new child element with the provided name and namespace |
|
406 declaration and adds it as the last child of its parent. |
|
407 |
|
408 Copies are taken of descripters passed in. |
|
409 |
|
410 @param aLocalName The name of the element |
|
411 @param aNsDecl The namespace declaration that must be retrieved from |
|
412 one of the ascendant nodes of the new elements (and its prefix |
|
413 should not be remapped to another namespace URI for the scope |
|
414 of the new element) |
|
415 @return Created element node |
|
416 @leave KXmlEngErrNullNode Element is NULL |
|
417 @leave KXmlEngErrWrongUseOfAPI Name is not specified |
|
418 @leave - One of the system-wide error codes |
|
419 */ |
|
420 IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aLocalName, TXmlEngNamespace aNsDecl); |
|
421 |
|
422 /** |
|
423 Creates a new child element with provided the name, prefix and namespace |
|
424 URI and adds it as the last child of its parent. |
|
425 |
|
426 The new namespace declaration will be attached to the parent (this) element |
|
427 and used as the namespace for newly created child element. If such a |
|
428 binding already exists (same prefix is bound to same URI), it will be |
|
429 reused. If the prefix is already bound to some other namespace URI, it will |
|
430 be rebound by the new namespace declaration node. |
|
431 |
|
432 Copies are taken of descripters passed in. |
|
433 |
|
434 @param aLocalName Name of the element |
|
435 @param aNsUri URI of the element's namespace |
|
436 @param aPrefix Prefix of the element |
|
437 @return The created element node |
|
438 @leave KXmlEngErrNullNode Element is NULL |
|
439 @leave KXmlEngErrWrongUseOfAPI Name or URI or prefix is not specified |
|
440 @leave - One of the system-wide error codes |
|
441 */ |
|
442 IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aLocalName, |
|
443 const TDesC8& aNsUri, |
|
444 const TDesC8& aPrefix); |
|
445 |
|
446 /** |
|
447 Creates a child element with the same namespace (and prefix if present) as |
|
448 the parent element and adds it as the last child of its parent. |
|
449 |
|
450 Copies are taken of descripters passed in. |
|
451 |
|
452 @param aLocalName The element's name |
|
453 @return The created element |
|
454 @leave KXmlEngErrNullNode Element is NULL |
|
455 @leave KXmlEngErrWrongUseOfAPI Name is not specified |
|
456 @leave - One of the system-wide error codes |
|
457 */ |
|
458 IMPORT_C TXmlEngElement AddNewElementSameNsL(const TDesC8& aLocalName); |
|
459 |
|
460 /** |
|
461 Performs a lookup for the namespace declaration for the specified prefix |
|
462 and adds a new child element with the found namespace as the last child of |
|
463 its parent. |
|
464 |
|
465 @pre The prefix is bound |
|
466 |
|
467 Copies are taken of descripters passed in. |
|
468 |
|
469 @param aLocalName The element's name |
|
470 @param aPrefix The prefix to use for the search |
|
471 @return The created element |
|
472 @leave KXmlEngErrNullNode Element is NULL |
|
473 @leave KXmlEngErrWrongUseOfAPI Name is not specified |
|
474 @leave KErrNoMemory The namespace is not found and the prefix is not "xml" |
|
475 (i.e http://www.w3.org/XML/1998/namespace); or there is a memory allocation |
|
476 error. |
|
477 @leave - One of the system-wide error codes |
|
478 */ |
|
479 IMPORT_C TXmlEngElement AddNewElementUsePrefixL(const TDesC8& aLocalName, const TDesC8& aPrefix); |
|
480 |
|
481 /** |
|
482 Performs a lookup for the namespace declaration for the specified namespace |
|
483 URI and adds a new child element with the found namespace. The new element |
|
484 is added as the last child of this element. |
|
485 |
|
486 Copies are taken of descripters passed in. |
|
487 |
|
488 @pre A namespace with the given URI has been declared |
|
489 |
|
490 @param aLocalName The element's name |
|
491 @param aNsUri The namespace of the element |
|
492 @return The created element |
|
493 @leave KXmlEngErrNullNode Element is NULL |
|
494 @leave KXmlEngErrWrongUseOfAPI Name is not specified |
|
495 @leave KErrNoMemory The namespace is not found and the URI is not http://www.w3.org/XML/1998/namespace |
|
496 or there is a memory allocation error |
|
497 @leave - One of the system-wide error codes |
|
498 */ |
|
499 IMPORT_C TXmlEngElement AddNewElementWithNsL(const TDesC8& aLocalName, const TDesC8& aNsUri); |
|
500 |
|
501 /** |
|
502 Creates a new child element. If there is no a prefix binding for the new |
|
503 element's namespace, a namespace decaration is created with a generated |
|
504 prefix at the specified element. |
|
505 |
|
506 The location of the namespace declaration may be controlled with |
|
507 aNsDeclTarget: |
|
508 |
|
509 @code |
|
510 el.AddNewElementAutoPrefixL(tagName,uri,KNullDesC8); // declare on the new element |
|
511 el.AddNewElementAutoPrefixL(tagName,uri,el); // declare on the parent element |
|
512 el.AddNewElementAutoPrefixL(tagName,uri,doc.DocumentElement()); // declare on the root element |
|
513 ... |
|
514 @endcode |
|
515 |
|
516 Note: The farther namespace declaration up in the document tree, the |
|
517 longer the namespace declaration lookups take. |
|
518 |
|
519 Copies are taken of descripters passed in. |
|
520 |
|
521 @param aLocalName Name of the element to create |
|
522 @param aNsUri Namespace URI of the new element |
|
523 @param aNsDeclTarget The element where the namespace declaraton should be placed. |
|
524 @return The created element |
|
525 @leave KXmlEngErrNullNode Element is NULL |
|
526 @leave KXmlEngErrWrongUseOfAPI Name or URI is not specified |
|
527 @leave - One of the system-wide error codes |
|
528 */ |
|
529 IMPORT_C TXmlEngElement AddNewElementAutoPrefixL(const TDesC8& aLocalName, |
|
530 const TDesC8& aNsUri, |
|
531 TXmlEngElement aNsDeclTarget); |
|
532 |
|
533 /** |
|
534 Gets element content. This method may be used in most cases when the element |
|
535 has only simple text content (without entity references embedded). If the |
|
536 element's contents is mixed (other types of nodes present), only the contents |
|
537 of the first child node is returned (if it is a TXmlEngTextNode node). |
|
538 |
|
539 For getting the contents of an element that has contents containing entity |
|
540 references, WholeTextValueCopyL() should be used. |
|
541 |
|
542 @see TXmlEngNode::WholeTextContentsCopyL() |
|
543 |
|
544 @return The simple text contents of the element or NULL if there is no text. |
|
545 */ |
|
546 IMPORT_C TPtrC8 Text() const; |
|
547 |
|
548 /** |
|
549 Adds text as a child of the element to the end of the list of children. |
|
550 |
|
551 Note: There may be several TXmlEngTextNode and TXmlEngEntityReference |
|
552 nodes added, depending on the aString value. For example, if the curernt |
|
553 node has text and attributes, a text node and attribute nodes will |
|
554 be added. |
|
555 |
|
556 Copies are taken of descripters passed in. |
|
557 |
|
558 @param aString Text to be added as the element's content. |
|
559 @leave KXmlEngErrNullNode Element is NULL |
|
560 @leave - One of the system-wide error codes |
|
561 */ |
|
562 IMPORT_C void AddTextL(const TDesC8& aString); |
|
563 |
|
564 /** |
|
565 Sets text contents for the element. Any child nodes are removed. |
|
566 This function is the same as TXmlEngNode::SetValueL(TDesC8&) |
|
567 |
|
568 @see TXmlEngNode::SetValueL(TDesC8&) |
|
569 |
|
570 @param aString Text to be set as element's content. |
|
571 @leave KXmlEngErrNullNode Element is NULL |
|
572 @leave - One of the system-wide error codes |
|
573 */ |
|
574 IMPORT_C void SetTextL(const TDesC8& aString); |
|
575 |
|
576 /** |
|
577 Sets the text content of the element from an escaped string. |
|
578 @see TXmlEngAttr::SetEscapedValueL(TDesC8&) |
|
579 |
|
580 @param aEscapedString New value |
|
581 @leave KXmlEngErrNullNode Element is NULL |
|
582 @leave - One of the system-wide error codes |
|
583 */ |
|
584 IMPORT_C void SetEscapedTextL(const TDesC8& aEscapedString); |
|
585 |
|
586 /** |
|
587 Sets the new element value exactly as presented in the string. Predefined |
|
588 entities are not converted into the characters they represent. Any child |
|
589 nodes are removed. |
|
590 |
|
591 @see TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue); |
|
592 |
|
593 @param aNotEncString New string value |
|
594 @leave KXmlEngErrNullNode Element is NULL |
|
595 @leave - One of the system-wide error codes |
|
596 */ |
|
597 IMPORT_C void SetTextNoEncL(const TDesC8& aNotEncString); |
|
598 |
|
599 /** |
|
600 Appends a new text node with the value exactly as presented in the string. |
|
601 Predefined entities are not converted into the characters they represent. |
|
602 Existing child nodes are not removed. |
|
603 |
|
604 @see TXmlEngAttr::SetValueNoEncL(const TDesC8& aNewValue); |
|
605 |
|
606 Copies are taken of descripters passed in. |
|
607 |
|
608 @param aNotEncString Appended string value |
|
609 @leave KXmlEngErrNullNode Element is NULL |
|
610 @leave - One of the system-wide error codes |
|
611 */ |
|
612 IMPORT_C void AppendTextNoEncL(const TDesC8& aNotEncString); |
|
613 |
|
614 /** |
|
615 Adds a namespace declaration to the current element: a binding of prefix to namespace URI. |
|
616 |
|
617 If the same namespace declaration exists (same prefix and URI), a redundant |
|
618 namespace declaration will not be created. |
|
619 |
|
620 Both KNullDesC8 or an empty descriptor may be used for "UNDEFINED URI" |
|
621 and "NO PREFIX" values of arguments. Please refer to the class |
|
622 documentation for more specific information. |
|
623 @see TXmlEngElement |
|
624 @see KNullDesC8 |
|
625 |
|
626 Note: Undeclaring of default namespace (xmlns="") is supported by |
|
627 the SetNoDefaultNamespace() method. |
|
628 @see SetNoDefaulNamespace() |
|
629 |
|
630 Note: Adding a namespace declaration that rebinds the prefix mapping (or |
|
631 default namespace) used by nodes lower in the tree may damage the document |
|
632 tree because references to namespace declarations are not updated. |
|
633 However, after serialization, the document will have the desired structure. |
|
634 Use this method with care! |
|
635 |
|
636 Copies are taken of descripters passed in. |
|
637 |
|
638 @param aNsUri Namespace URI, KNullDesC8 or an empty descriptor. |
|
639 @param aPrefix Namespace prefix, KNullDesC8 or an empty descriptor. |
|
640 @return The namespace that was created or found or a NULL namespace if the |
|
641 namespace is being undeclared. |
|
642 @leave KXmlEngErrNullNode Element is NULL |
|
643 @leave KXmlEngErrWrongUseOfAPI URI or prefix is not specified |
|
644 @leave - One of the system-wide error codes |
|
645 */ |
|
646 IMPORT_C TXmlEngNamespace AddNamespaceDeclarationL(const TDesC8& aNsUri, const TDesC8& aPrefix); |
|
647 |
|
648 /** |
|
649 Adds a default namespace declaration. |
|
650 |
|
651 1 |
|
652 This achieves the same result as with AddNamespaceDeclarationL(aNsUri, |
|
653 KNullDesC8), but additionally the element's namespace is modified (if it has no |
|
654 prefix and there were no default namespace declaration in the scope) to the |
|
655 new default one. |
|
656 |
|
657 Copies are taken of descripters passed in. |
|
658 @see KNullDesC8 |
|
659 |
|
660 @param aNsUri Namespace URI; KNullDesC8 and empty descriptor are allowed to represent UNDEFINED NAMSPACE |
|
661 @return The created namespace declaration (NULL for UNDEFINED NAMESPACE) |
|
662 @leave KXmlEngErrNullNode Element is NULL |
|
663 @leave KXmlEngErrWrongUseOfAPI URI is not specified |
|
664 @leave - One of the system-wide error codes |
|
665 */ |
|
666 IMPORT_C TXmlEngNamespace SetDefaultNamespaceL(const TDesC8& aNsUri); |
|
667 |
|
668 /** |
|
669 Undeclares any default namespace for this element and its descendants. |
|
670 |
|
671 If there is already a default namespace, a @c xmlns="" namespace |
|
672 declaration is added. Otherwise, nothing happens, since elements with no |
|
673 prefix in such scope are automaticaly considered outside of any namespace. |
|
674 |
|
675 The side effect of this method is that the namespace of the current element |
|
676 may change from the previous default namespace to a NULL TXmlEngNamespace, |
|
677 which is considered an absence of namespace. |
|
678 |
|
679 If the element has a prefix (i.e. not having default namespace), then the |
|
680 only effect for the element is undeclaration of existing default namespace. |
|
681 |
|
682 If the element is in the scope of another @c xmlns="" undeclaration, no |
|
683 action is taken. |
|
684 |
|
685 Note: Use AddNamespaceDeclarationL(KNullDesC8,KNullDesC8) to force the creation of a @c |
|
686 xmlns="" declaration within the scope of another such declaration |
|
687 (otherwise unneccessary/duplicate declarations are not created). |
|
688 |
|
689 Note: This method should be called on elements before adding children, |
|
690 because default namespace undeclaration is not spread into its subtree and |
|
691 descendants' default namespaces are not reset to NULL. This should be taken |
|
692 into account if later some processing on the subtree occurs. However, |
|
693 after serialization and deserialization, undeclared default namespace will |
|
694 affect whole element's subtree correctly. |
|
695 |
|
696 @see KNullDesC8 |
|
697 |
|
698 @leave KXmlEngErrNullNode Element is NULL |
|
699 @leave - One of the system-wide error codes |
|
700 */ |
|
701 IMPORT_C void SetNoDefaultNamespaceL(); |
|
702 |
|
703 /** |
|
704 Finds the namespace declaration that has a specific prefix in the list of parents for |
|
705 this element. |
|
706 |
|
707 If no prefix is specified (an empty descriptor or KNullDesC8) then it is |
|
708 considered to be a "NO PREFIX" search. Therefore, if the namespace |
|
709 declaration for "no prefix" is searched, then the default namespace is |
|
710 returned. |
|
711 |
|
712 Copies are taken of descripters passed in. |
|
713 @see KNullDesC8 |
|
714 |
|
715 @param aPrefix Namespace prefix. |
|
716 @return The namespace, which may be NULL if prefix is not found; NULL result for "no prefix" means that default namespace is undefined. |
|
717 @leave - One of the system-wide error codes |
|
718 */ |
|
719 IMPORT_C TXmlEngNamespace LookupNamespaceByPrefixL(const TDesC8& aPrefix) const; |
|
720 |
|
721 /** |
|
722 Finds a namespace declaration that has a specific namespace URI in the |
|
723 scope for the given node. |
|
724 |
|
725 KNullDesC8 value of aUri is equivalent to an empty descriptor and means |
|
726 "UNDEFINED NAMESPACE". |
|
727 For such URI's a NULL namespace handle is always returned even if there is |
|
728 a namespace undeclaration, which has an empty descriptor URI (and KNullDesC8 |
|
729 prefix). |
|
730 |
|
731 Hint: Use the returned instance of TXmlEngNamespace as the aNsDef argument |
|
732 to an element's methods that create new child elements and attributes. The |
|
733 same TXmlEngNamespace may be used on deeper descentants of the reference |
|
734 element (and doing this way will generally increase performance of DOM tree |
|
735 construction). However, if namespace bindings are not controlled for the |
|
736 element's children and the prefix (which is bound to the search namespace) |
|
737 is rebound to some other namespace URI, then reusing the namespace may lead |
|
738 to unwanted result. |
|
739 |
|
740 Note: At the moment it is possible to retrieve namespace declaration nodes |
|
741 whose prefixes were rebound. Be careful when using returned |
|
742 TXmlEngNamespace objects for creation of new elements. |
|
743 |
|
744 Copies are taken of descripters passed in. |
|
745 |
|
746 @param aUri Namespace URI, for which the namespace declaration is searched |
|
747 @return The namespace declaration that binds the given namespace URI to a |
|
748 prefix or sets it as a default namespace |
|
749 @leave - One of the system-wide error codes |
|
750 */ |
|
751 IMPORT_C TXmlEngNamespace LookupNamespaceByUriL(const TDesC8& aUri) const; |
|
752 |
|
753 /** |
|
754 Retrieves the implicitly declared XML infoset binding of the 'xml' prefix |
|
755 to XML's namespace URI: "http://www.w3.org/XML/1998/namespace" |
|
756 |
|
757 The result should be used for creating attributes beloging to the XML namespace |
|
758 (xml:lang, xml:space, xml:id , etc.) |
|
759 |
|
760 DO NOT USE the methods LookupNamespaceByUriL(const TDesC8&) and |
|
761 LookupNamespaceByPrefixL(const TDesC8&) (with the arguments |
|
762 "http://www.w3.org/XML/1998/namespace" and "xml" respectively) for |
|
763 retrieving the namespace node, since in the case of a memory allocation |
|
764 fault, a NULL result is returned (and breaks your program silently) |
|
765 |
|
766 Note: Normally the 'xml' prefix is bound to the XML namespace URI in the |
|
767 document node, BUT if this element is not a part of the document tree yet, |
|
768 the requested namespace declaration WILL BE ADDED to the current node. |
|
769 This is the reason why the method may fail in OOM conditions. |
|
770 |
|
771 @return The namespace matching the prefix binding |
|
772 {xml,"http://www.w3.org/XML/1998/namespace"} in the current document |
|
773 @leave KErrNoMemory The element is NULL or there was a memory allocation error |
|
774 @leave - One of the system-wide error codes |
|
775 */ |
|
776 IMPORT_C TXmlEngNamespace TheXMLNamespaceL() const; |
|
777 |
|
778 /** |
|
779 Get the default namespace for the element. |
|
780 |
|
781 A NULL TXmlEngNamespace means that an element with no prefix |
|
782 has no namespace associated with it because no default namespace was declared or |
|
783 the default namespace was undeclared with @c xmlns="" |
|
784 |
|
785 This function is equivalent to LookupNamespaceByPrefixL(KNullDesC8). |
|
786 @see KNullDesC8 |
|
787 |
|
788 @return The default namespace in the scope of the element |
|
789 @leave - One of the system-wide error codes |
|
790 */ |
|
791 inline TXmlEngNamespace DefaultNamespaceL() const; |
|
792 |
|
793 /** |
|
794 Performs a search for the namespace in the scope of the element. This |
|
795 method will create new namespace declaration on the element if such |
|
796 namespace is not found. |
|
797 |
|
798 Note: Be sure not to use the result of this method for non-descendants of |
|
799 the element or in situations when prefix overlapping might occur. |
|
800 @see TXmlEngAttr |
|
801 @see TXmlEngNamespace |
|
802 Please read the documentation for this class: |
|
803 @see TXmlEngElement |
|
804 |
|
805 Copies are taken of descripters passed in. |
|
806 |
|
807 @param aNsUri Namespace to search for |
|
808 @param aPrefix Prefix to use for the new namespace declaration (if it is to be created) |
|
809 @return The namespace found or created |
|
810 @leave KXmlEngErrNullNode Element is NULL |
|
811 @leave KXmlEngErrWrongUseOfAPI URI is not specified |
|
812 @leave - One of the system-wide error codes |
|
813 |
|
814 @see LookupNamespacebyUriL |
|
815 */ |
|
816 IMPORT_C TXmlEngNamespace FindOrCreateNsDeclL(const TDesC8& aNsUri, const TDesC8& aPrefix); |
|
817 |
|
818 /** |
|
819 Performs a search on the element and its ascendants for any namespace |
|
820 declaration with a given URI. Creates a new namespace declaration with a |
|
821 (unique) prefix if the search was not successful. |
|
822 @see AddNamespaceDeclarationL |
|
823 |
|
824 Copies are taken of descripters passed in. |
|
825 |
|
826 @param aNsUri Namespace to search for |
|
827 @return The namespace found or created |
|
828 @leave KXmlEngErrNullNode Element is NULL |
|
829 @leave KXmlEngErrWrongUseOfAPI URI is not specified |
|
830 @leave - One of the system-wide error codes |
|
831 */ |
|
832 IMPORT_C TXmlEngNamespace FindOrCreateNsDeclL(const TDesC8& aNsUri); |
|
833 |
|
834 /** |
|
835 Checks whether a prefix has been bound in this element (not in one of its ascendants) |
|
836 |
|
837 Use this method for preventing prefix-name collision in a element node |
|
838 |
|
839 Copies are taken of descripters passed in. |
|
840 |
|
841 @param aPrefix Namespace prefix |
|
842 @return ETrue if there is already a namespace declaration that uses aPrefix on this element |
|
843 @leave - One of the system-wide error codes |
|
844 */ |
|
845 IMPORT_C TBool HasNsDeclarationForPrefixL(const TDesC8& aPrefix) const; |
|
846 |
|
847 /** |
|
848 Copies the element with its attributes, but not child nodes |
|
849 |
|
850 If the context is preserved (preserveNsContent), then all namespace |
|
851 declarations that are in the element are writen to the <element ...> tag. |
|
852 |
|
853 @param preserveNsContext Whether the namespace context should be preserved |
|
854 @return The copied element |
|
855 @leave KXmlEngErrNullNode The element is NULL |
|
856 @leave - One of the system-wide error codes |
|
857 */ |
|
858 IMPORT_C TXmlEngElement ElementCopyNoChildrenL(TBool preserveNsContext) const; |
|
859 |
|
860 /** |
|
861 Specialized version of TXmlEngNode::CopyL() |
|
862 @return Deep copy of the element. |
|
863 @leave KXmlEngErrNullNode The element is NULL |
|
864 @leave - One of the system-wide error codes |
|
865 */ |
|
866 inline TXmlEngElement CopyL() const; |
|
867 |
|
868 /** Resets element's content: all child nodes are removed */ |
|
869 IMPORT_C void RemoveChildren(); |
|
870 |
|
871 /** Resets element's attributes */ |
|
872 IMPORT_C void RemoveAttributes(); |
|
873 |
|
874 /** |
|
875 Resets all namespace declarations made in the element |
|
876 |
|
877 Note: There can be references to these namespace declarations elsewhere! |
|
878 Use ReconcileNamespacesL() to fix that. |
|
879 */ |
|
880 IMPORT_C void RemoveNamespaceDeclarations(); |
|
881 |
|
882 /** |
|
883 Removes all element contents: child nodes, attributes and namespace declarations |
|
884 |
|
885 @see RemoveChildren() |
|
886 @see RemoveAttributes() |
|
887 @see RemoveNamespaceDeclarations(); |
|
888 */ |
|
889 inline void ClearElement(); |
|
890 |
|
891 /** |
|
892 Copies attributes from another element. It may be a very convenient method |
|
893 for initializing element with a set of predefined attributes. |
|
894 |
|
895 Note: Namespaces of the this element may need to be reconciled if the |
|
896 copied attributes belong to any namespace that is not declared on some |
|
897 ascendant of this node. @see ReconcileNamespacesL() |
|
898 |
|
899 @param aSrc Source element |
|
900 @leave KXmlEngErrNullNode The element is NULL |
|
901 @leave - One of the system-wide error codes |
|
902 */ |
|
903 IMPORT_C void CopyAttributesL(TXmlEngElement aSrc); |
|
904 |
|
905 /** |
|
906 Recursively copies the children (and all of it's associated information) |
|
907 from another element. Elements are appended to the current element's |
|
908 children list. |
|
909 |
|
910 Note: Namespaces of this element may need to be reconciled after copy |
|
911 operation |
|
912 @see ReconcileNamespacesL() |
|
913 |
|
914 @param aSrc Source element |
|
915 @leave KXmlEngErrNullNode The element is NULL |
|
916 @leave KXmlEngWrongUseOfAPI The source element is NULL |
|
917 @leave - One of the system-wide error codes |
|
918 */ |
|
919 IMPORT_C void CopyChildrenL(TXmlEngElement aSrc); |
|
920 |
|
921 /** |
|
922 Removes the child element with the given name and namespace URI (if it exists). |
|
923 Memory allocated for the element is freed. |
|
924 |
|
925 @param aLocalName Child element name |
|
926 @param aNamespaceUri Child element namespace |
|
927 @leave KXmlEngErrNullNode The element is NULL |
|
928 @leave - One of the system-wide error codes |
|
929 */ |
|
930 IMPORT_C void RemoveChildElementsL(const TDesC8& aLocalName,const TDesC8& aNamespaceUri); |
|
931 |
|
932 /** |
|
933 Renames the element with the given name, namespace URI, and namespace prefix. |
|
934 |
|
935 @param aLocalName The new element name |
|
936 @param aNamespaceUri The new namespace URI |
|
937 @param aPrefix The new namespace prefix |
|
938 @leave - One of the system-wide error codes |
|
939 */ |
|
940 IMPORT_C void RenameElementL(const TDesC8& aLocalName, const TDesC8& aNamespaceUri, const TDesC8& aPrefix); |
|
941 |
|
942 /* |
|
943 DOM Level 3 Core methods |
|
944 |
|
945 Most methods of DOM spec operate with fully-qualified names (QNames) |
|
946 of elements and attributes. It is different in this API - all methods |
|
947 instead accept prefix and localName parts of QName. |
|
948 */ |
|
949 |
|
950 /** |
|
951 Returns the value of the attribute with the given name and namespace URI. |
|
952 |
|
953 @param aLocalName Local name of the attribute |
|
954 @param aNamespaceUri Namespace URI of the attribute, or the default namespace if not specified. |
|
955 @return The attribute value (for as long as the attribute exists) or |
|
956 NULL if not found. |
|
957 @leave - One of the system-wide error codes |
|
958 */ |
|
959 IMPORT_C TPtrC8 AttributeValueL(const TDesC8& aLocalName, |
|
960 const TDesC8& aNamespaceUri = KNullDesC8) const; |
|
961 |
|
962 /** |
|
963 Initializes list of child elements with matching names and namespace URIs. |
|
964 |
|
965 Note: This method does not list all descendants of the element, only child elements |
|
966 @see KNullDesC8 |
|
967 |
|
968 @param aList Node list to be created |
|
969 @param aLocalName Element name |
|
970 @param aNamespaceUri if specified it sets the Namespace URI, default is KNullDesC8 (no namespace set). |
|
971 @leave - One of the system-wide error codes |
|
972 */ |
|
973 IMPORT_C void GetElementsByTagNameL(RXmlEngNodeList<TXmlEngElement>& aList, |
|
974 const TDesC8& aLocalName, |
|
975 const TDesC8& aNamespaceUri = KNullDesC8) const; |
|
976 |
|
977 /** |
|
978 Sets the value of the given attribute. The attribute is created if there |
|
979 is no such attribute yet. |
|
980 |
|
981 Note: If prefix is not KNullDesC8 (or an empty descriptor), |
|
982 then the namespace URI may not be empty see |
|
983 http://www.w3.org/TR/REC-xml-names/#ns-decl (Definition #3) |
|
984 |
|
985 Copies are taken of descripters passed in. |
|
986 @see KNullDesC8 |
|
987 |
|
988 @param aLocalName Attribute name |
|
989 @param aValue Attribute value |
|
990 @param aNamespaceUri Namespace URI - default is KNullDesC8 |
|
991 @param aPrefix Namespace prefix - default is KNullDesC8 |
|
992 @leave KXmlEngErrNullNode The element is NULL |
|
993 @leave KXmlEngErrWrongUseOfAPI Attribute name not specified |
|
994 @leave - One of the system-wide error codes |
|
995 */ |
|
996 IMPORT_C void SetAttributeL(const TDesC8& aLocalName, |
|
997 const TDesC8& aValue, |
|
998 const TDesC8& aNamespaceUri = KNullDesC8, |
|
999 const TDesC8& aPrefix = KNullDesC8); |
|
1000 |
|
1001 /** |
|
1002 Removes the attribute with the given name and namespace URI (if it exists). |
|
1003 Memory allocated for the attribute is freed. |
|
1004 |
|
1005 @see KNullDesC8 |
|
1006 |
|
1007 @param aLocalName Name of the attribute |
|
1008 @param aNamespaceUri Attribute namespace URI, default is KNullDesC8 |
|
1009 @leave - One of the system-wide error codes |
|
1010 */ |
|
1011 IMPORT_C void RemoveAttributeL(const TDesC8& aLocalName, |
|
1012 const TDesC8& aNamespaceUri = KNullDesC8); |
|
1013 |
|
1014 /** |
|
1015 Retrieves an attribute node with a specific namespace by its name. |
|
1016 |
|
1017 @see KNullDesC8 |
|
1018 |
|
1019 @param aLocalName Name of the attribute |
|
1020 @param aNamespaceUri Attribute namespace URI, default is KNullDesC8 |
|
1021 @return Attribute node with matching namespace URI and name, NULL if not found. |
|
1022 @leave - One of the system-wide error codes |
|
1023 */ |
|
1024 IMPORT_C TXmlEngAttr AttributeNodeL(const TDesC8& aLocalName, |
|
1025 const TDesC8& aNamespaceUri = KNullDesC8) const; |
|
1026 |
|
1027 /** |
|
1028 Check if the element has an attribute with given parameters. |
|
1029 |
|
1030 This function is the same as AttributeNodeL(uri,name).NotNull(). |
|
1031 |
|
1032 @see KNullDesC8 |
|
1033 |
|
1034 @param aLocalName Name of attribute |
|
1035 @param aNamespaceUri Namespace uri, default is KNullDesC8. |
|
1036 @return ETrue if the element holds an attribute with such namespace URI and name. |
|
1037 @leave - One of the system-wide error codes |
|
1038 */ |
|
1039 inline TBool HasAttributeL(const TDesC8& aLocalName, |
|
1040 const TDesC8& aNamespaceUri = KNullDesC8) const; |
|
1041 |
|
1042 /** |
|
1043 Adds an attribute to this element. If an attribute of the same name |
|
1044 exists, it will be destroyed. |
|
1045 |
|
1046 @param aNewAttr The new attribute |
|
1047 @leave KXmlEngErrNullNode The element or attribute is NULL |
|
1048 @leave - One of the system-wide error codes |
|
1049 */ |
|
1050 IMPORT_C void SetAttributeNodeL(TXmlEngAttr aNewAttr); |
|
1051 }; |
|
1052 |
|
1053 |
|
1054 #include <xml/dom/xmlengelement.inl> |
|
1055 |
|
1056 #endif /* XMLENGELEMENT_H */ |
|
1057 |