|
1 /* |
|
2 * Copyright (c) 2004-2006 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: Node class declaration |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 |
|
20 |
|
21 |
|
22 |
|
23 |
|
24 #ifndef XMLENGINE_NODE_H_INCLUDED |
|
25 #define XMLENGINE_NODE_H_INCLUDED |
|
26 |
|
27 #include <e32base.h> |
|
28 |
|
29 // forward declaration |
|
30 class TXmlEngNode; |
|
31 |
|
32 // Forward declarations |
|
33 template<class T> class RXmlEngNodeList; |
|
34 |
|
35 class RXmlEngDocument; |
|
36 class TXmlEngElement; |
|
37 class TXmlEngAttr; |
|
38 class TXmlEngTextNode; |
|
39 class TXmlEngNamespace; |
|
40 class TXmlEngComment; |
|
41 class TXmlEngCDATASection; |
|
42 class TXmlEngDocumentFragment; |
|
43 class TXmlEngEntityReference; |
|
44 class TXmlEngProcessingInstruction; |
|
45 class MXmlEngUserData; |
|
46 class TXmlEngBinaryContainer; |
|
47 class TXmlEngChunkContainer; |
|
48 class TXmlEngDataContainer; |
|
49 class TXmlEngFileContainer; |
|
50 // |
|
51 |
|
52 /** |
|
53 * Instance of TXmlEngNode class represents an XML node in the DOM tree. |
|
54 * |
|
55 * Class implements methods that are similar for all XML node types |
|
56 * i.e. element, attribute. |
|
57 * |
|
58 * Sample code for node tree modifications: |
|
59 * @code |
|
60 * RXmlEngDOMImplementation domImpl; |
|
61 * domImpl.OpenL(); ///< opening DOM implementation object |
|
62 * RXmlEngDocument iDoc; ///< iDoc with created nodes tree |
|
63 * TXmlEngNode tmp = iDoc.DocumentElement(); |
|
64 * ///< copying first child of iDoc to tmp2 node and appending it |
|
65 * TXmlEngNode tmp2 = tmp.FirstChild().CopyL(); |
|
66 * tmp.AppendChildL(tmp2); |
|
67 * ///< copying next node to the first child of iDoc to the last child place |
|
68 * tmp.FirstChild().NextSibling().CopyToL(tmp.LastChild()); |
|
69 * ///< replasing before last child with second child |
|
70 * tmp.LastChild().PreviousSibling().ReplaceWith(tmp.FirstChild().NextSibling()); |
|
71 * ///< moving first child of iDoc to second child childrens |
|
72 * tmp.FirstChild().MoveTo(tmp.FirstChild().NextSibling()); |
|
73 * iDoc.Close(); ///< closing all opened objects |
|
74 * domImpl.Close(); |
|
75 * @endcode |
|
76 * |
|
77 * @lib XmlEngineDOM.lib |
|
78 * @since S60 v3.1 |
|
79 */ |
|
80 class TXmlEngNode |
|
81 { |
|
82 public: |
|
83 /** |
|
84 * The different element types carried by an XML tree. |
|
85 * |
|
86 * @note This is synchronized with DOM Level 3 values |
|
87 * See http://www.w3.org/TR/DOM-Level-3-Core/ |
|
88 * |
|
89 */ |
|
90 enum TXmlEngDOMNodeType { |
|
91 EElement = 1, |
|
92 EAttribute = 2, |
|
93 EText = 3, |
|
94 ECDATASection = 4, |
|
95 EEntityReference = 5, |
|
96 EEntity = 6, //> Not supported currently |
|
97 EProcessingInstruction = 7, |
|
98 EComment = 8, |
|
99 EDocument = 9, |
|
100 EDocumentType = 10, //> Not supported currently |
|
101 EDocumentFragment = 11, |
|
102 ENotation = 12, //> Not supported currently |
|
103 ENamespaceDeclaration = 18, //> Not in DOM spec |
|
104 EBinaryContainer = 30, //> Not in DOM spec |
|
105 EChunkContainer = 31, //> Not in DOM spec |
|
106 EFileContainer = 32 //> Not in DOM spec |
|
107 }; |
|
108 |
|
109 public: |
|
110 /** |
|
111 * Default constructor |
|
112 * |
|
113 * @since S60 v3.1 |
|
114 */ |
|
115 inline TXmlEngNode(); |
|
116 |
|
117 /** |
|
118 * Constructor |
|
119 * |
|
120 * @since S60 v3.1 |
|
121 * @param aInternal node pointer |
|
122 */ |
|
123 inline TXmlEngNode(void* aInternal); |
|
124 |
|
125 /** |
|
126 * Check if node is NULL |
|
127 * |
|
128 * @since S60 v3.1 |
|
129 * @return TRUE if node is NULL in other case FALSE |
|
130 */ |
|
131 inline TBool IsNull() const; |
|
132 |
|
133 /** |
|
134 * Check if node is NULL |
|
135 * |
|
136 * @since S60 v3.1 |
|
137 * @return TRUE if node is not NULL in other case FALSE |
|
138 */ |
|
139 inline TBool NotNull()const; |
|
140 |
|
141 /** |
|
142 * Cast node to attribute node. |
|
143 * |
|
144 * @since S60 v3.1 |
|
145 * @return Attribute node |
|
146 * |
|
147 * @note |
|
148 * - Never cast nodes to a wrong node type! |
|
149 * - Casting removes const'ness of the node |
|
150 */ |
|
151 inline TXmlEngAttr& AsAttr() const; |
|
152 |
|
153 /** |
|
154 * Cast node to text node. |
|
155 * |
|
156 * @since S60 v3.1 |
|
157 * @return Text node |
|
158 * |
|
159 * @note |
|
160 * - Never cast nodes to a wrong node type! |
|
161 * - Casting removes const'ness of the node |
|
162 */ |
|
163 inline TXmlEngTextNode& AsText() const; |
|
164 |
|
165 /** |
|
166 * Cast node to binary data container |
|
167 * |
|
168 * @since S60 v3.2 |
|
169 * @return Binary container |
|
170 * |
|
171 * @note |
|
172 * - Never cast nodes to a wrong node type! |
|
173 * - Casting removes const'ness of the node |
|
174 */ |
|
175 inline TXmlEngBinaryContainer& AsBinaryContainer() const; |
|
176 |
|
177 /** |
|
178 * Cast node to memory chunk container |
|
179 * |
|
180 * @since S60 v3.2 |
|
181 * @return Chunk container |
|
182 * |
|
183 * @note |
|
184 * - Never cast nodes to a wrong node type! |
|
185 * - Casting removes const'ness of the node |
|
186 */ |
|
187 inline TXmlEngChunkContainer& AsChunkContainer() const; |
|
188 |
|
189 /** |
|
190 * Cast node to file container |
|
191 * |
|
192 * @since S60 v3.2 |
|
193 * @return File container |
|
194 * |
|
195 * @note |
|
196 * - Never cast nodes to a wrong node type! |
|
197 * - Casting removes const'ness of the node |
|
198 */ |
|
199 inline TXmlEngFileContainer& AsFileContainer() const; |
|
200 |
|
201 /** |
|
202 * Cast node to memory chunk container |
|
203 * |
|
204 * @since S60 v3.1 |
|
205 * @return Chunk container |
|
206 * |
|
207 * @note |
|
208 * - Never cast nodes to a wrong node type! |
|
209 * - Casting removes const'ness of the node |
|
210 */ |
|
211 inline TXmlEngDataContainer& AsDataContainer() const; |
|
212 |
|
213 /** |
|
214 * Cast node to element node. |
|
215 * |
|
216 * @since S60 v3.1 |
|
217 * @return Element node |
|
218 * |
|
219 * @note |
|
220 * - Never cast nodes to a wrong node type! |
|
221 * - Casting removes const'ness of the node |
|
222 */ |
|
223 inline TXmlEngElement& AsElement() const; |
|
224 |
|
225 /** |
|
226 * Cast node to comment node. |
|
227 * |
|
228 * @since S60 v3.1 |
|
229 * @return Comment node |
|
230 * |
|
231 * @note |
|
232 * - Never cast nodes to a wrong node type! |
|
233 * - Casting removes const'ness of the node |
|
234 */ |
|
235 inline TXmlEngComment& AsComment() const; |
|
236 |
|
237 /** |
|
238 * Cast node to namespace node. |
|
239 * |
|
240 * @since S60 v3.1 |
|
241 * @return Namespace node |
|
242 * |
|
243 * @note |
|
244 * - Never cast nodes to a wrong node type! |
|
245 * - Casting removes const'ness of the node |
|
246 */ |
|
247 inline TXmlEngNamespace& AsNamespace() const; |
|
248 |
|
249 /** |
|
250 * Cast node to CDATA section node. |
|
251 * |
|
252 * @since S60 v3.1 |
|
253 * @return CDATA section node |
|
254 * |
|
255 * @note |
|
256 * - Never cast nodes to a wrong node type! |
|
257 * - Casting removes const'ness of the node |
|
258 */ |
|
259 inline TXmlEngCDATASection& AsCDATASection() const; |
|
260 |
|
261 /** |
|
262 * Cast node to entity reference node. |
|
263 * |
|
264 * @since S60 v3.1 |
|
265 * @return Entity reference node |
|
266 * |
|
267 * @note |
|
268 * - Never cast nodes to a wrong node type! |
|
269 * - Casting removes const'ness of the node |
|
270 */ |
|
271 inline TXmlEngEntityReference& AsEntityReference() const; |
|
272 |
|
273 /** |
|
274 * Cast node to processing instruction node. |
|
275 * |
|
276 * @since S60 v3.1 |
|
277 * @return Processing instruction node |
|
278 * |
|
279 * @note |
|
280 * - Never cast nodes to a wrong node type! |
|
281 * - Casting removes const'ness of the node |
|
282 */ |
|
283 inline TXmlEngProcessingInstruction& AsProcessingInstruction() const; |
|
284 |
|
285 /** |
|
286 * Get innerXML string. This method returns all content of the node. |
|
287 * Output text does not include node markup. |
|
288 * |
|
289 * @since S60 v3.1 |
|
290 * @param aBuffer RBuf8 in which output should be save |
|
291 * @return Size of output buffer |
|
292 * @note Returned RBuf8 should be freed |
|
293 */ |
|
294 IMPORT_C TInt InnerXmlL(RBuf8& aBuffer); |
|
295 |
|
296 /** |
|
297 * Get outerXML string. This method returns all content of the node. |
|
298 * Output text includes node markup. |
|
299 * |
|
300 * @since S60 v3.1 |
|
301 * @param aBuffer RBuf8 in which output should be save |
|
302 * @return Size of output buffer |
|
303 * @note Returned RBuf8 should be freed |
|
304 */ |
|
305 IMPORT_C TInt OuterXmlL(RBuf8& aBuffer); |
|
306 |
|
307 /** |
|
308 * Moves the node to become the first in the list of its siblings |
|
309 * Node is expected to have a parent. |
|
310 * |
|
311 * @since S60 v3.1 |
|
312 */ |
|
313 IMPORT_C void SetAsFirstSibling(); |
|
314 |
|
315 /** |
|
316 * Moves the node to become the last in the list of its siblings |
|
317 * Node is expected to have a parent. |
|
318 * |
|
319 * @since S60 v3.1 |
|
320 */ |
|
321 IMPORT_C void SetAsLastSibling(); |
|
322 |
|
323 /** |
|
324 * Moves the node in the list of sibling nodes before another node |
|
325 * Node is expected to have a parent. |
|
326 * Do nothing if aSiblingNode is not one of node's siblings |
|
327 * |
|
328 * @since S60 v3.1 |
|
329 * @param aSiblingNode Node that should be after current node |
|
330 */ |
|
331 IMPORT_C void MoveBeforeSibling(TXmlEngNode aSiblingNode); |
|
332 |
|
333 /** |
|
334 * Moves the node in the list of sibling nodes after another node |
|
335 * Node is expected to have a parent. |
|
336 * Do nothing if aSiblingNode is not one of the node's siblings |
|
337 * |
|
338 * @since S60 v3.1 |
|
339 * @param aSiblingNode Node that should be after current node |
|
340 */ |
|
341 IMPORT_C void MoveAfterSibling(TXmlEngNode aSiblingNode); |
|
342 |
|
343 /** |
|
344 * Moves the node to another part of the tree or another document |
|
345 * The node is unliked from current postion (if any) and appended |
|
346 * to the its new parent. |
|
347 * |
|
348 * @since S60 v3.1 |
|
349 * @param aParent Parent node |
|
350 * @return Node handle |
|
351 * |
|
352 * @note |
|
353 * In many cases this method call should be followed by ReconcileNamespacesL() on the moved node |
|
354 */ |
|
355 inline TXmlEngNode MoveTo(TXmlEngNode aParent); |
|
356 |
|
357 /** |
|
358 * Detaches a node from document tree |
|
359 * |
|
360 * @since S60 v3.1 |
|
361 * @return This node, which is already not a part of any document |
|
362 * @note Remember to use ReconcileNamespacesL() later, if extracted node (subtree) |
|
363 * contains references to namespace declarations outside of the subtree. |
|
364 * @see ReconcileNamespacesL() |
|
365 * @note The document, from which the is being unlinked, becomes an owner of the node |
|
366 * until it is linked elsewhere. |
|
367 */ |
|
368 IMPORT_C TXmlEngNode Unlink(); |
|
369 |
|
370 /** |
|
371 * Ensures that namespaces referred to in the node and its descendants are |
|
372 * in the scope the node. |
|
373 * |
|
374 * This method checks that all the namespaces declared within the given |
|
375 * tree are properly declared. This is needed for example after Copy or Unlink |
|
376 * and then Append operations. The subtree may still hold pointers to |
|
377 * namespace declarations outside the subtree or they may be invalid/masked. As much |
|
378 * as possible the function try to reuse the existing namespaces found in |
|
379 * the new environment. If not possible, the new namespaces are redeclared |
|
380 * on the top of the subtree. |
|
381 * |
|
382 * This method should be used after unlinking nodes and inserting to another |
|
383 * document tree or to a another part of the original tree, if some nodes of the subtree |
|
384 * are remove from the scope of a namespace declaration they refer to. |
|
385 * |
|
386 * When node is unlinked, it may still refer to namespace declarations from the previous location. |
|
387 * It is important to reconcile subtree's namespaces if previous parent tree is to be destroyed. |
|
388 * On the other hand, if the parent tree is not changed before pasting its unlinked part into another |
|
389 * tree, then reconciliation is needed only after paste operation. |
|
390 * |
|
391 * @since S60 v3.1 |
|
392 */ |
|
393 IMPORT_C void ReconcileNamespacesL(); |
|
394 |
|
395 /** |
|
396 * Unlinks the node and destroys it; all child nodes are destroyed as well and all memory is freed |
|
397 * |
|
398 * @note Document nodes cannot be "removed" with this method, uses RXmlEngDocument-specific methods. |
|
399 * |
|
400 * @since S60 v3.1 |
|
401 */ |
|
402 IMPORT_C void Remove(); |
|
403 |
|
404 /** |
|
405 * Current node is replaced with another node (subtree). |
|
406 * |
|
407 * The replacement node is linked into document tree instead of this node. |
|
408 * The replaced node is destroyed. |
|
409 * |
|
410 * @since S60 v3.1 |
|
411 * @param aNode Node that repleace current node |
|
412 * |
|
413 * @see SubstituteFor(TXmlEngNode) |
|
414 * |
|
415 * In both cases the argument node is unlinked from its previous location |
|
416 * (which can be NONE, i.e. not linked; SAME or ANOTHER document tree). |
|
417 * |
|
418 * @note Replacement of a node with NULL TXmlEngNode is legal and equivalent to removing the node. |
|
419 * @note Not applicable to document nodes |
|
420 */ |
|
421 IMPORT_C void ReplaceWith(TXmlEngNode aNode); |
|
422 |
|
423 /** |
|
424 * Another node is put instead of the current node. |
|
425 * |
|
426 * Does the same as ReplaceWith(TXmlEngNode) but does not free node and just returns it. |
|
427 * |
|
428 * @since S60 v3.1 |
|
429 * @param aNode Node that repleace current node |
|
430 * @return Current node after unlinking it from document tree |
|
431 * @see ReplaceWith(TXmlEngNode) |
|
432 * |
|
433 * In both cases the argument node is unlinked from its previous location |
|
434 * (which can be NONE, i.e. not linked; SAME or ANOTHER document tree) |
|
435 * |
|
436 * It is possible to use NULL TXmlEngNode object as an argument. In such case |
|
437 * no new node will be put instead of unlinked one. |
|
438 * |
|
439 * @note Not applicable to document nodes |
|
440 */ |
|
441 IMPORT_C TXmlEngNode SubstituteForL(TXmlEngNode aNode); |
|
442 |
|
443 /** |
|
444 * Retrieves a "handle" for namespace declaration that applies to the node's namespace |
|
445 * Note: DOM specs do not consider namespace declarations as a kind of nodes |
|
446 * This API adds TXmlEngNamespace type of nodes, which is derived from TXmlEngNode. |
|
447 * |
|
448 * @since S60 v3.1 |
|
449 * @return Object that represents namespace declaration and prefix binding that |
|
450 * act on the node; returns NULL object (check using TXmlEngNamespace.IsNull() |
|
451 * or TXmlEngNamespace.NotNull()) if no namespace associated |
|
452 */ |
|
453 IMPORT_C TXmlEngNamespace NamespaceDeclaration() const; |
|
454 |
|
455 /** |
|
456 * Attaches a user data object to this node. The ownership of the object is transferred. |
|
457 * When the (underlying) node is deleted the Destroy method of the MXmlEngUserData class will be |
|
458 * called. If there already is a user data object associated with this node, it will be |
|
459 * deleted before attaching the new object. |
|
460 * |
|
461 * @since S60 v3.1 |
|
462 * @param aData Pointer to the data object. |
|
463 * @return true if successful, false if for example underlying node type doesn't support |
|
464 * attaching user data. |
|
465 * @note Only TXmlEngElement and Attribute nodes currently support this feature. |
|
466 * User data is not copied, when node is copied. |
|
467 */ |
|
468 IMPORT_C TBool AddUserData(MXmlEngUserData* aData); |
|
469 |
|
470 /** |
|
471 * Returns the user data object attached to this node. Ownership is not transferred. |
|
472 * |
|
473 * @since S60 v3.1 |
|
474 * @return Pointer to data object or NULL if it doesn't exist. |
|
475 */ |
|
476 IMPORT_C MXmlEngUserData* UserData() const; |
|
477 |
|
478 /** |
|
479 * Removes the user data onject attached to this node. Ownership is transferred |
|
480 * (the object is not deleted). |
|
481 * |
|
482 * @since S60 v3.1 |
|
483 * @return Pointer to data object or NULL if it doesn't exist. |
|
484 */ |
|
485 IMPORT_C MXmlEngUserData* RemoveUserData(); |
|
486 |
|
487 /** |
|
488 * Clones the node completely: all attributes and namespace declarations (for TXmlEngElement nodes), |
|
489 * values and children nodes are copied as well. |
|
490 * |
|
491 * Document nodes cannot be copied with this method: RXmlEngDocument::CloneDocumentL() must be used. |
|
492 * |
|
493 * @since S60 v3.1 |
|
494 * @return Complete copy of a node or leaves. |
|
495 * @note The node should not be NULL! |
|
496 */ |
|
497 IMPORT_C TXmlEngNode CopyL() const; |
|
498 |
|
499 /** |
|
500 * Creates a deep copy of the node and appends the subtree as a new child |
|
501 * to the provided parent node. |
|
502 * |
|
503 * @since S60 v3.1 |
|
504 * @return Created copy of the node after linking it into the target document tree. |
|
505 * @note Document nodes cannot be copied with this method; use RXmlEngDocument::CloneDocumentL() |
|
506 */ |
|
507 IMPORT_C TXmlEngNode CopyToL(TXmlEngNode aParent) const; |
|
508 |
|
509 /** |
|
510 * Append a child node. |
|
511 * |
|
512 * This is universal operation for any types of nodes. |
|
513 * Note, that some types of nodes cannot have children and |
|
514 * some types of nodes are not allowed to be children of some other types. |
|
515 * |
|
516 * @since S60 v3.1 |
|
517 * @param aNewChild Child node that should be added |
|
518 * @return Appended node, which could changed as a result of adding it to |
|
519 * list of child nodes (e.g. text nodes can coalesce together) |
|
520 */ |
|
521 IMPORT_C TXmlEngNode AppendChildL(TXmlEngNode aNewChild); |
|
522 |
|
523 /** |
|
524 * Initializes a node list with all children of the node |
|
525 * |
|
526 * @since S60 v3.1 |
|
527 * @param aList node list that should be initialized |
|
528 */ |
|
529 IMPORT_C void GetChildNodes(RXmlEngNodeList<TXmlEngNode>& aList) const; |
|
530 |
|
531 /** |
|
532 * Get parent node of current node. |
|
533 * |
|
534 * @since S60 v3.1 |
|
535 * @return Parent node of the node or NULL if no parent |
|
536 */ |
|
537 IMPORT_C TXmlEngNode ParentNode() const; |
|
538 |
|
539 /** |
|
540 * Get first child of current node |
|
541 * |
|
542 * @since S60 v3.1 |
|
543 * @return The first child node or NULL if no children |
|
544 */ |
|
545 IMPORT_C TXmlEngNode FirstChild() const; |
|
546 |
|
547 /** |
|
548 * Get last child of current node |
|
549 * |
|
550 * @since S60 v3.1 |
|
551 * @return The last child node or NULL if no children |
|
552 */ |
|
553 IMPORT_C TXmlEngNode LastChild() const; |
|
554 |
|
555 /** |
|
556 * Get previous node of current node |
|
557 * |
|
558 * @since S60 v3.1 |
|
559 * @return Previous node in a child list or NULL if no sibling before |
|
560 */ |
|
561 IMPORT_C TXmlEngNode PreviousSibling() const; |
|
562 |
|
563 /** |
|
564 * Get fallowing node of current node |
|
565 * |
|
566 * @since S60 v3.1 |
|
567 * @return Following node in a child list or NULL if no sibling after |
|
568 */ |
|
569 IMPORT_C TXmlEngNode NextSibling() const; |
|
570 |
|
571 /** |
|
572 * Get document handle |
|
573 * |
|
574 * @since S60 v3.1 |
|
575 * @return A document node of the DOM tree this node belongs to |
|
576 * |
|
577 * @note An instance of RXmlEngDocument class returns itself |
|
578 */ |
|
579 IMPORT_C RXmlEngDocument OwnerDocument() const; |
|
580 |
|
581 /** |
|
582 * Fetches value of this node, depending on its type. |
|
583 * |
|
584 * @note It is better to always cast nodes to specific type and then use specific |
|
585 * method for getting "node value" |
|
586 * |
|
587 * @since S60 v3.1 |
|
588 * @return Node value |
|
589 */ |
|
590 IMPORT_C TPtrC8 Value() const; |
|
591 |
|
592 /** |
|
593 * Get copy of node's text content |
|
594 * What is returned depends on the node type. |
|
595 * Method caller is responsible for freeing returned string. |
|
596 * |
|
597 * @since S60 v3.1 |
|
598 * @return the content of the node |
|
599 */ |
|
600 IMPORT_C void WholeTextContentsCopyL(RBuf8& aOutput) const; |
|
601 |
|
602 /** |
|
603 * Sets value of this node. |
|
604 * |
|
605 * @since S60 v3.1 |
|
606 * @param aValue New value |
|
607 */ |
|
608 IMPORT_C void SetValueL(const TDesC8& aValue); |
|
609 |
|
610 /** |
|
611 * Check if node content is "simple text". |
|
612 * |
|
613 * @since S60 v3.1 |
|
614 * @return Whether the value of the node is presented by only one TXmlEngTextNode node |
|
615 * |
|
616 * If the value is <i>"simple text"</i> then it is possible to access it as TDOMString |
|
617 * without making copy, which combines values of all text nodes and entity reference nodes. |
|
618 * |
|
619 * @see TXmlEngNode::Value(), TXmlEngAttr::Value(), TXmlEngElement::Text() |
|
620 * |
|
621 * This method is applicable to TXmlEngElement and TXmlEngAttr nodes. On other nodes FALSE is returned. |
|
622 * |
|
623 * @note |
|
624 * Values (contents) of TXmlEngComment, TXmlEngCDATASection, TXmlEngTextNode, ProcessingInstuction data are |
|
625 * always "simple". |
|
626 * |
|
627 * When the returned result is FALSE, getting value of the node would not returned |
|
628 * whole contents because of either entity references present in the contents or |
|
629 * the contents is mixed (for TXmlEngElement node). In this case WholeTextContentsCopyL() |
|
630 * should be used. |
|
631 * |
|
632 * @see TXmlEngNode::WholeTextContentsCopyL() |
|
633 */ |
|
634 IMPORT_C TBool IsSimpleTextContents() const; |
|
635 |
|
636 /** |
|
637 * Use NodeType() to find out the type of the node prior to casting object |
|
638 * of TXmlEngNode class to one of its derived subclasses (TXmlEngElement, TXmlEngAttr, TXmlEngTextNode, etc.) |
|
639 * |
|
640 * @since S60 v3.1 |
|
641 * @return Type of the node |
|
642 * |
|
643 * @see TXmlEngDOMNodeType |
|
644 */ |
|
645 IMPORT_C TXmlEngDOMNodeType NodeType() const; |
|
646 |
|
647 /** |
|
648 * Get node name |
|
649 * |
|
650 * @since S60 v3.1 |
|
651 * @return Name of the node |
|
652 * |
|
653 * This method generally follows DOM spec : |
|
654 * ------------------------------------------------------------------------------- |
|
655 * The values of nodeName, nodeValue, and attributes vary according to the node |
|
656 * type as follows: |
|
657 * |
|
658 * interface nodeName nodeValue attributes |
|
659 * ------------------------------------------------------------------------------- |
|
660 * Attr = Attr.name = Attr.value = null |
|
661 * CDATASection = "#cdata-section" = CharacterData.data = null |
|
662 * Comment = "#comment" = CharacterData.data = null |
|
663 * Document = "#document" = null = null |
|
664 * DocumentFragment = "#document-fragment" = null = null |
|
665 * DocumentType = DocumentType.name = null = null |
|
666 * Element = Element.tagName = null = NamedNodeMap |
|
667 * Entity = entity name = null = null |
|
668 * EntityReference = name of entity referenced = null = null |
|
669 * Notation = notation name = null = null |
|
670 * ProcessingInstruction = target = data = null |
|
671 * Text = "#text" = CharacterData.data = null |
|
672 * ------------------------------------------------------------------------------- |
|
673 */ |
|
674 IMPORT_C TPtrC8 Name() const; |
|
675 |
|
676 |
|
677 /** |
|
678 * Check if node has child nodes. |
|
679 * |
|
680 * @since S60 v3.1 |
|
681 * @return True if the node is TXmlEngElement and has at least one child node |
|
682 */ |
|
683 IMPORT_C TBool HasChildNodes() const; |
|
684 |
|
685 /** |
|
686 * Check if node has attributes. |
|
687 * |
|
688 * @since S60 v3.1 |
|
689 * @return True if the node is TXmlEngElement and has at least one attribute |
|
690 * |
|
691 * @note Namespace-to-prefix bindings are not attributes. |
|
692 */ |
|
693 IMPORT_C TBool HasAttributes() const; |
|
694 |
|
695 /** |
|
696 * Evaluates active base URI for the node by processing xml:base attributes of parents |
|
697 * |
|
698 * @since S60 v3.1 |
|
699 * @return A copy of effective base URI for the node |
|
700 * @note It's up to the caller to free the string |
|
701 */ |
|
702 IMPORT_C void BaseUriL(RBuf8& aBaseUri) const; |
|
703 |
|
704 /** |
|
705 * Compares nodes. |
|
706 * |
|
707 * The nodes are the same if they are referring to the same in-memory |
|
708 * data structure. |
|
709 * |
|
710 * @since S60 v3.1 |
|
711 * @param aOther Node to compare |
|
712 * @return TRUE if the same |
|
713 */ |
|
714 inline TBool IsSameNode(TXmlEngNode aOther) const; |
|
715 |
|
716 /** |
|
717 * Get namespace uri. |
|
718 * |
|
719 * @since S60 v3.1 |
|
720 * @return Namespace URI of a node |
|
721 * - NULL is returned for elements and attributes that do not |
|
722 * belong to any namespace. |
|
723 * - bound namespace URI is returned for namespace declaration nodes (instances of TXmlEngNamespace). |
|
724 * - NULL is returned to all other types of node. |
|
725 * |
|
726 * @note use IsNull() and NotNull() for testing returned result on the subject |
|
727 * of having some URI |
|
728 */ |
|
729 IMPORT_C TPtrC8 NamespaceUri() const; |
|
730 |
|
731 /** |
|
732 * Get namespace prefix. |
|
733 * |
|
734 * @since S60 v3.1 |
|
735 * @return Prefix of a node |
|
736 * Returns NULL for elements and attributes that do not have prefix |
|
737 * (node belongs to the default namespace or does not belong to any namespace) |
|
738 * NULL is also returned for all types of node other than TXmlEngElement or TXmlEngAttr |
|
739 */ |
|
740 IMPORT_C TPtrC8 Prefix() const; |
|
741 |
|
742 /** |
|
743 * Check if nemespace is default for this node |
|
744 * |
|
745 * @since S60 v3.1 |
|
746 * @param aNamespaceUri Namespace URI |
|
747 * @return True if given namespace URI is a default one for the node (applicable to elements only) |
|
748 * |
|
749 * @note "" or NULL can be used to denote undefined namespace |
|
750 */ |
|
751 IMPORT_C TBool IsDefaultNamespaceL(const TDesC8& aNamespaceUri) const; |
|
752 |
|
753 /** |
|
754 * Searches the prefix that is bound to the given aNamespaceUri and |
|
755 * applicable in the scope of this TXmlEngNode. |
|
756 * |
|
757 * @since S60 v3.1 |
|
758 * @param aNamespaceUri Namespace Uri that should be found |
|
759 * @return A sought prefix or NULL if not found or aNamespaceUri is the default namespace |
|
760 * |
|
761 * @see TXmlEngElement::LookupNamespaceByUriL(const TDesC8&) |
|
762 */ |
|
763 IMPORT_C TPtrC8 LookupPrefixL(const TDesC8& aNamespaceUri) const; |
|
764 |
|
765 /** |
|
766 * Searches the namespace URI that is bound to the given prefix. |
|
767 * |
|
768 * @since S60 v3.1 |
|
769 * @param aPrefix Namespace prefix that should be found |
|
770 * @return A sought URI or NULL if the prefix is not bound |
|
771 * |
|
772 * @see TXmlEngElement::LookupNamespaceByPrefixL(const TDesC8&) |
|
773 */ |
|
774 IMPORT_C TPtrC8 LookupNamespaceUriL(const TDesC8& aPrefix) const; |
|
775 |
|
776 protected: |
|
777 /** |
|
778 * Unlinks the internal libxml2's node from double-linked list. |
|
779 * Relinks neighbour nodes.The node stays virtually linked to its old neighbours! Use with care!! |
|
780 * |
|
781 * No checks are made; nor parent's, nor node's properties updated |
|
782 * |
|
783 * @since S60 v3.1 |
|
784 */ |
|
785 void DoUnlinkNode(); |
|
786 |
|
787 /** |
|
788 * Inserts the node in a double-linked list of nodes before specified node. |
|
789 * |
|
790 * No checks are made; nor parent's, nor node's properties updated (except prev/next) |
|
791 * |
|
792 * @since S60 v3.1 |
|
793 * @param aNode Target node |
|
794 */ |
|
795 void LinkBefore(TXmlEngNode aNode); |
|
796 |
|
797 protected: |
|
798 /** Node pointer */ |
|
799 void* iInternal; |
|
800 |
|
801 }; |
|
802 |
|
803 #include "xmlengnode.inl" |
|
804 |
|
805 #endif /* XMLENGINE_NODE_H_INCLUDED */ |