2 * Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies).
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".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
14 * Description: This is an optimized variant of XML element, which consumes
15 * significantly less heap when compared to CSenBaseElement
26 #ifndef SEN_XML_ELEMENT_H
27 #define SEN_XML_ELEMENT_H
31 #include <SenElement.h>
32 #include <SenNameSpace.h>
33 #include <SenBaseAttribute.h>
38 * Implementation of an XML element functionality
39 * Content is stored in UTF-8 form XML. Note, that
40 * setting any 8-bit content into XML without encoding
41 * it into form of legal is illegal. Instead, one
42 * should use encoding methods, like ones introduced
43 * in SenXmlUtils class to encode basic entities, or
44 * use use some other encoding like MD5 for binary
49 class CSenXmlElement : public CSenElement
51 public: // Constructors and destructor
54 * Standard constructor.
55 * @param aLocalName the local name for this element.
57 * KErrSenInvalidCharacters if aLocalName contains illegal characters.
58 * KErrSenZeroLengthDescriptor if aLocalName is zero length.
61 IMPORT_C static CSenXmlElement* NewL(const TDesC8& aLocalName);
63 * Standard constructor.
64 * @param aNsUri the namespace URI for this element.
65 * @param aLocalName the local name for this element.
67 * KErrSenInvalidCharacters if aLocalName contains illegal characters.
68 * KErrSenZeroLengthDescriptor if aLocalName is zero length.
70 IMPORT_C static CSenXmlElement* NewL(const TDesC8& aNsUri,
71 const TDesC8& aLocalName);
74 * Standard constructor.
75 * @param aNsUri the namespace URI for this element.
76 * @param aLocalName the local name for this element.
77 * @param aQName the qualified name for this element.
79 * KErrSenInvalidCharacters if aLocalName or aQName contains
81 * KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
83 IMPORT_C static CSenXmlElement* NewL(const TDesC8& aNsUri,
84 const TDesC8& aLocalName,
85 const TDesC8& aQName);
88 * Standard constructor.
89 * @param aNsUri the namespace URI for this element.
90 * @param aLocalName the local name for this element.
91 * @param aQName the qualified name for this element.
92 * @param apAttrs the attributes for this element.
94 * KErrSenInvalidCharacters if aLocalName or aQName contains
96 * KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
98 IMPORT_C static CSenXmlElement* NewL(const TDesC8& aNsUri,
99 const TDesC8& aLocalName,
100 const TDesC8& aQName,
101 const RAttributeArray& apAttrs);
104 * Standard constructor.
105 * @param aNsUri the namespace URI for this element.
106 * @param aLocalName the local name for this element.
107 * @param aQName the qualified name for this element.
108 * @param apAttrs the attributes for this element.
109 * @param aParent: the parent element for the new element
111 * KErrSenInvalidCharacters if aLocalName or aQName contains
112 * illegal characters.
113 * KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
115 IMPORT_C static CSenXmlElement* NewL(const TDesC8& aNsUri,
116 const TDesC8& aLocalName,
117 const TDesC8& aQName,
118 const RAttributeArray& apAttrs,
119 CSenElement& aParent);
124 IMPORT_C virtual ~CSenXmlElement();
126 public: // New functions
129 * Adds attributes to the element. Calls internally AddAttributesL()
130 * Can be overridden to replace old attributes.
131 * @param aAttrs: the array of attributes.
133 IMPORT_C virtual void SetAttributesL(const RAttributeArray& apAttrs);
135 // Functions from base classes
140 * Getter for Element's local name.
141 * @return Localname or KNullDesC if not set.
143 IMPORT_C virtual const TDesC8& LocalName() const;
146 * Getter for Element's namespace URI.
147 * @return Namespace URI or KNullDesC if not set.
149 IMPORT_C virtual const TDesC8& NamespaceURI() const;
152 * Getter for namespace prefix of this element.
153 * @return namespace prefix or KNullDesC if not set.
155 IMPORT_C virtual const TDesC8& NsPrefix() const;
158 * Setter for namespace prefix of this element.
159 * @param aPrefix: new namespace prefix for the element.
161 IMPORT_C virtual void SetPrefixL(const TDesC8& aPrefix);
164 * Method for checking if the element has any content within.
165 * @return ETrue if has content, EFalse if not.
167 IMPORT_C virtual TBool HasContent() const;
170 * Getter for the content of the element.
171 * @return the content or KNullDesC if empty.
173 IMPORT_C virtual TPtrC8 Content() const;
176 * Getter for the content of the element, unicode version.
177 * @return content as unicode. Ownership IS TRANSFERRED to the caller.
179 IMPORT_C virtual HBufC* ContentUnicodeL() const;
182 * Sets the content to the element. Old content is overwritten.
183 * @param aContent: The content to be set. Can be KNullDesC8.
184 * @return The content of the element or KNullDesC8 if no content was set.
186 IMPORT_C virtual TPtrC8 SetContentL(const TDesC8& aContent);
189 * Gets the write stream for the content for easy appending.
190 * Writing 8-bit (UTF-8) string to the returned stream will be appended
192 * @return reference to the RWriteStream.
194 IMPORT_C virtual RWriteStream& ContentWriteStreamL();
197 * Checks if element matches to another element
198 * by its content and child elements. Element
199 * can contain more data than the given pattern.
200 * @since Series60 3.0
201 * @param aCandidate The pattern to be matched. Must contain same or
202 * less data for match to come true.
203 * @return ETrue if content and possible children match exactly
204 * to given pattern. EFalse otherwise.
206 IMPORT_C virtual TBool ConsistsOfL(MSenElement& aCandidate);
209 * Setter for Element's namespace URI.
210 * @param aNsUri: Namespace URI
212 IMPORT_C virtual void SetNamespaceL(const TDesC8& aNsUri);
215 * Setter for Element's namespace URI.
216 * @param aNsPrefix: Namespace prefix
217 * @param aNsUri: Namespace URI
219 IMPORT_C virtual void SetNamespaceL(const TDesC8& aNsPrefix,
220 const TDesC8& aNsUri);
223 * Adds a namespace declaration.
224 * If this element (or its parent if parameter aCheckInParent is ETrue)
225 * already has a Namespace with the same prefix and URI the given
226 * Namespace is not added.
227 * @param aNewNamespace
228 * @param aCheckInParent
229 * @return the added Namespace, or the equivalent pre-existing one.
231 IMPORT_C virtual const CSenNamespace* AddNamespaceL(CSenNamespace& aNewNamespace,
232 TBool aCheckInParent);
234 * Method for adding a namespace for the Element.
235 * @param aPrefix: Namespace prefix
236 * @param aUri: Namespace URI
237 * @return the added Namespace, or the equivalent pre-existing one.
239 IMPORT_C virtual const CSenNamespace* AddNamespaceL(const TDesC8& aPrefix,
242 * Getter for Element's namespace.
243 * @return const pointer to the CSenNamespace object of this Element.
246 IMPORT_C virtual const CSenNamespace* Namespace();
249 * Getter for new namespace, using a namespace prefix as a search criteria.
250 * @param aNsPrefix is the new namespace prefix for this element
251 * @return the found Namespace that is declared for the given prefix
252 * within the scope of this Element. If no such prefix is
253 * declared return null.
255 IMPORT_C virtual const CSenNamespace* Namespace(const TDesC8& aNsPrefix);
258 * Getter for new namespace, using a namespace prefix as a search criteria,
259 * supporting both normal and recursive search mode (checking the parent).
260 * @param aNsPrefix: The prefix used to search
261 * @param aCheckInParent: The flag indicating whether to check parent's
262 * namespaces too if not found in the current
264 * ETrue to check, EFalse for not to check.
265 * @return the found Namespace that is declared for the given prefix
266 * and namespace URI within the scope of this Element
267 * or NULL if not found
269 IMPORT_C virtual const CSenNamespace* Namespace(const TDesC8& aNsPrefix,
270 const TBool aCheckInParent);
273 * Getter for new namespace, using both namespace prefix and namespace URI as search criteria.
274 * @param aNsPrefix: The prefix used to search
275 * @param aUri: The namespace URI used to search.
276 * @return the found Namespace that is declared for the given prefix
277 * and namespace URI within the scope of this Element
278 * or NULL if not found.
280 IMPORT_C virtual const CSenNamespace* Namespace(const TDesC8& aNsPrefix,
284 * Getting the child elements of this element matching the given criteria.
285 * @param aElementArray: Array to be filled with the matching elements,
286 * or empty array if no matching found.
287 * Any modifications made on the returned items
288 * modify the real childs too.
289 * @param aNsUri: namespace URI to be matched
290 * @param aLocalName: local name to be matched
291 * @return KErrNone ok
292 * KErrNotFound No child elements exist.
294 IMPORT_C virtual TInt ElementsL(RPointerArray<CSenElement>& aElementArray,
295 const TDesC8& aNsUri,
296 const TDesC8& aLocalName);
299 * Getting the child elements of this element matching the given criteria.
300 * @param aElementArray: Array to be filled with the matching elements,
301 * or empty array if no matching found.
302 * Any modifications made on the returned items
303 * modify the real childs too.
304 * @param aNsUri: namespace URI to be matched
305 * @param aLocalName: local name to be matched
306 * @return KErrNone ok
307 * KErrNotFound No child elements exist.
309 IMPORT_C virtual TInt ElementsL(RPointerArray<CSenElement>& aElementArray,
310 const TDesC8& aLocalName);
313 * Getting the child elements of this element.
314 * @return an array of child elements. This is an empty array if there
315 * are no children. Any modifications made on the returned array
316 * modify the element object.
318 IMPORT_C virtual RPointerArray<CSenElement>& ElementsL();
321 * Gets all the attributes of this element in an array.
322 * @return array of attributes. Array will be empty if element has
325 IMPORT_C virtual RPointerArray<CSenBaseAttribute>& AttributesL();
328 * Gets all the namespaces of this element in an array.
329 * @return array of namespaces. Array will be empty if element has
332 IMPORT_C virtual RPointerArray<CSenNamespace>& NamespacesL();
335 * Gets the value of the given attribute.
336 * @param aName: Name of the attribute in question.
337 * @return the value of the attribute, or NULL if not found. Ownership is
340 IMPORT_C virtual const TDesC8* AttrValue(const TDesC8& aName);
343 * Adds an attribute. If attribute is already existing,
344 * the value of the attribute will be replaced.
346 IMPORT_C virtual void AddAttrL(const TDesC8& aName, const TDesC8& aValue);
349 * Gets the parent element of this element.
350 * @return the parent element or NULL if no parent set.
351 * Ownership is NOT transferred to the caller.
353 IMPORT_C virtual CSenElement* Parent();
356 * Sets the parent element to this element. Notice that the element is not
357 * automatically added as a child of the parent. Parent's
358 * AddElementL() should be called instead.
359 * @param apParent: The wanted parent. Can be NULL.
360 * @return the parent element
362 IMPORT_C virtual CSenElement* SetParent(CSenElement* apParent);
365 * Gets the root element. If no parent element, returns this element.
366 * @return the root of the tree. Ownership is NOT transferred.
368 IMPORT_C virtual MSenElement& Root();
371 * Gets the child element with the specified local name.
372 * Assumes that namespace is the same as this parent element.
373 * @return the child element or NULL if the child with the specified
374 * local name is not found. Ownership is NOT transferred.
376 IMPORT_C virtual CSenElement* Element(const TDesC8& aLocalName);
379 * Gets the child element with the specified local name and namespace URI.
380 * @return the child element or NULL if the child with the specified
381 * criterias is not found. Ownership is NOT transferred.
383 IMPORT_C virtual CSenElement* Element(const TDesC8& aNsUri,
384 const TDesC8& aLocalName);
387 * Create a new element ready for adding or insertion.
388 * If the given namespace prefix is not declared yet
389 * the element will not be created and NULL will be returned.
390 * @param aNsPrefix: The namespace prefix
391 * @param aLocalName: The new elements localname
392 * @return the new Element just created, or NULL if given prefix was not
393 * declared yet. Ownership is transferred to the caller.
395 * KErrSenInvalidCharacters if aLocalName contains illegal characters.
396 * KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
398 IMPORT_C virtual CSenElement* CreateElementL(const TDesC8& aNsPrefix,
399 const TDesC8& aLocalName);
402 * Insert an Element into the list of children elements
403 * so that the inserted Element is placed right before the aBeforeElement.
404 * If aBeforeElement is not found, element will be appended to the last
406 * Function leaves if error occurs in inserting.
407 * @param aInsertedElement: the element to be inserted.
408 * Ownership is transferred.
409 * @param aBeforeElement: the element which will be right next to the
410 * element just inserted.
411 * @return the inserted Element
413 IMPORT_C virtual CSenElement& InsertElementL(CSenElement& aElement,
414 const CSenElement& aBeforeElement);
417 * Adds an Element to the children elements.
418 * Sets this element to be the new parent of the given element.
419 * @param aElement: the element to be added. Ownership is transferred.
420 * @return the added Element
422 IMPORT_C virtual CSenElement& AddElementL(CSenElement& aElement);
425 * Constructs and adds a new element to the children elements.
426 * Sets this element to be the new parent of the given element.
427 * @param aNsUri: namespace URI of the new element
428 * @param aLocalName: local name of the new element
429 * @return the added Element
431 * KErrSenInvalidCharacters if aLocalName contains illegal characters.
432 * KErrSenZeroLengthDescriptor if aLocalName is zero length.
434 IMPORT_C virtual CSenElement& AddElementL(const TDesC8& aNsUri,
435 const TDesC8& aLocalName);
438 * Constructs and adds a new element to the children elements.
439 * Sets this element to be the new parent of the given element.
440 * @param aNsUri: namespace URI of the new element
441 * @param aLocalName: local name of the new element
442 * @param aQName: qualified name of the new element
443 * @return the added Element
445 * KErrSenInvalidCharacters if aLocalName or aQName contain illegal
447 * KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
449 IMPORT_C virtual CSenElement& AddElementL(const TDesC8& aNsUri,
450 const TDesC8& aLocalName,
451 const TDesC8& aQName);
454 * Constructs and adds a new element to the children elements.
455 * Sets this element to be the new parent of the given element.
456 * Note: Element is created with no specific namespace, default namespace
457 * of some of the upper level elements are in effect if there is such a
459 * @param aLocalName: local name of the new element
460 * @return the added Element
462 * KErrSenInvalidCharacters if aLocalName contains illegal characters.
463 * KErrSenZeroLengthDescriptor if aLocalName is zero length.
465 IMPORT_C virtual CSenElement& AddElementL(const TDesC8& aLocalName);
468 * Remove an element from the childs.
469 * @param aElement: the element to be removed.
470 * @return The removed element. May be NULL if nothing was removed
471 * (if element was not found from the childs).
472 * The caller TAKES OWNERSHIP of the removed element.
474 IMPORT_C virtual CSenElement* RemoveElement(CSenElement& aElement);
477 * Remove an element from the childs.
478 * @param aNsUri: the namespace URI of the element to be removed.
479 * @param aLocalName: the local name of the element to be removed.
480 * @return The removed element. May be NULL if nothing was removed
481 * (if element was not found from the childs).
482 * The caller TAKES OWNERSHIP of the removed element.
484 IMPORT_C virtual CSenElement* RemoveElement(const TDesC8& aNsUri,
485 const TDesC8& aLocalName);
488 * Remove an element from the childs.
489 * @param aLocalName: the local name of the element to be removed.
490 * @return The removed element. May be NULL if nothing was removed
491 * (if element was not found from the childs).
492 * The caller TAKES OWNERSHIP of the removed element.
494 IMPORT_C virtual CSenElement* RemoveElement(const TDesC8& aLocalName);
497 * Replaces an element from the childs with another element.
498 * Element's local name and namespace URI will be used to match the
499 * element to be replaced. If matching element is not found, will
500 * normally add the given element to the childs.
501 * @param aElement: the element to be added. Ownership is transferred.
502 * @return The old element. May be NULL if nothing was replaced
503 * (if element was not found from the childs).
504 * The caller TAKES OWNERSHIP of the old element.
506 IMPORT_C virtual CSenElement* ReplaceElementL(CSenElement& aElement);
509 * Gets the element as an XML buffer. Buffer will contain all the childs
510 * @return element as XML. Caller takes ownership.
512 IMPORT_C virtual HBufC8* AsXmlL();
515 * Gets the element as an unicode XML buffer.
516 * Buffer will contain all the childs etc.
517 * @return element as XML. Caller takes ownership.
519 IMPORT_C virtual HBufC* AsXmlUnicodeL();
522 * Element writes itself to a write stream using UTF-8 charset encoding.
523 * @param aWriteStream: The stream to write to.
525 IMPORT_C virtual void WriteAsXMLToL(RWriteStream& aWriteStream);
528 * Element writes its namespaces to a write stream using UTF-8 charset
530 * @param aWriteStream: The stream to write to.
532 IMPORT_C virtual void WriteNamespacesToL(RWriteStream& aWriteStream);
535 * Gets the current element as XML element. Mostly used to get the
536 * classes which implement this interface as an instance of this
538 * @return the current object as element. Ownership is NOT transferred.
540 IMPORT_C virtual MSenElement* AsElement();
543 * Copies content from given element to this element appending to the
544 * existing content if there is any.
545 * @param aSource: The source element.
547 IMPORT_C void CopyFromL(CSenElement& aSource);
550 * Detach the element from its parent.
551 * If the element, or one of its children, is dependent
552 * on a namespace declared in the scope of the parent
553 * copy those namespace declarations to this element.
554 * @return this Element. Ownership IS TRANSFERRED to the caller.
556 IMPORT_C virtual CSenElement* DetachL();
559 * Gets a child element from a specified index.
560 * @param aIndex: the index what to get
561 * @return child element from a current index. NULL if no child in given
564 IMPORT_C virtual CSenElement* Child(TInt aIndex);
567 * (Re-) Set the name and namespace of this Element. The element will be
568 * given the localName in the the given namespace. A prefix will be
569 * computed from the qualified name.
570 * This method should be used with care and is mainly intended for
571 * protected use in implementations.
572 * @param aNamespaceURI: The new namespace URI.
573 * @param aLocalName: The new local name.
574 * @param aQName: The new qualified name.
576 IMPORT_C virtual void Set(const TDesC8& aNsUri,
577 const TDesC8& aLocalName,
578 const TDesC8& aQName);
581 * Adds new attributes to the element.
582 * @param aAttrs: the array of attributes.
584 IMPORT_C virtual void AddAttributesL(const RAttributeArray& apAttrs);
588 protected: // New functions
591 * C++ default constructor.
593 IMPORT_C CSenXmlElement();
596 * Following BaseConstructL methods should be called from the deriving
597 * classes ConstructL() methods. Parameter info is found in the
598 * corresponding NewL-methods.
600 IMPORT_C void BaseConstructL(const TDesC8& aLocalName);
602 IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
603 const TDesC8& aLocalName);
605 IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
606 const TDesC8& aLocalName,
607 const TDesC8& aQName);
609 IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
610 const TDesC8& aLocalName,
611 const TDesC8& aQName,
612 const RAttributeArray& apAttrs);
614 IMPORT_C void BaseConstructL(const TDesC8& aNsUri,
615 const TDesC8& aLocalName,
616 const TDesC8& aQName,
617 const RAttributeArray& apAttrs,
618 CSenElement& aParent);
621 * Method for finding an attribute with given name.
622 * @param aName a name of the attribute to be searched for
623 * @return the 1st attribute with the name, or NULL.
624 * Ownership is not transferred.
626 IMPORT_C virtual CSenBaseAttribute* FindAttr(const TDesC8& aName);
629 * Method for finding index for a wanted element.
630 * @param aNsUri a namespace URI which needs to match
631 * @param aLocalName a local name which needs to match
632 * @return Index of the element with given characteristics.
633 * or KErrNotFound if none matching
635 IMPORT_C virtual TInt IndexOfElement(const TDesC8& aNsUri,
636 const TDesC8& aLocalName) const;
639 * Writes element's attributes into a writestream.
640 * @param aWriteStream writestream to write into
642 IMPORT_C virtual void WriteAttrsToL(RWriteStream& aWriteStream);
645 * Helper function to write an attribute into a writestream.
646 * @param aWriteStream writestream to write into
647 * @param aName attribute name
648 * @param aValue attribute value
650 IMPORT_C virtual void WriteAttrToL(RWriteStream& aWriteStream,
652 const TDesC8& aValue);
655 * Writes all internal elements into a writestream.
656 * @param aWriteStream writestream to write into
658 IMPORT_C virtual void WriteElementsToL(RWriteStream& aWriteStream);
661 * Writes all element's content into a writestream.
662 * @param aWriteStream writestream to write into
664 IMPORT_C virtual void WriteContentToL(RWriteStream& aWriteStream);
667 * Adds an attribute into this element. Used also adding new namespaces
669 * @param aQName Attribute's qualified name
670 * @param aLocalName Attribute's local name
671 * @param aValue Attribute's value
672 * @return value of the attribute as string (TDesC&)
674 * KErrSenInvalidCharacters if aLocalName or aQName contain illegal
676 * KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
678 IMPORT_C virtual const TDesC8& AddAttributeL(const TDesC8& aQName,
679 const TDesC8& aLocalName,
680 const TDesC8& aValue);
683 * Adds an attribute into this element. Used also adding new namespaces
685 * @param aLocalName Attribute's local name
686 * @param aValue Attribute's value
687 * @return value of the attribute as string (TDesC&)
689 * KErrSenInvalidCharacters if aLocalName contains illegal characters.
690 * KErrSenZeroLengthDescriptor if aAttrName is zero length, or
691 * if the local name part of it is zero length.
693 IMPORT_C virtual const TDesC8& AddAttributeL(const TDesC8& aAttrName,
694 const TDesC8& aValue);
697 * Adds an attribute into this element.
698 * @param apAttribute Attribute to be added. Ownership is transferred
700 * @return attribute value as a string (TDesC8&)
702 IMPORT_C const TDesC8& AddAttributeL(CSenBaseAttribute* apAttribute);
705 * Allocates a new buffer for saving content, if none allocated yet.
707 IMPORT_C virtual void AllocContentBufL();
710 * Writes element into a dynamic buffer.
711 * @param aBuf a dynamic buffer where to append everything.
712 * @return the modified buffer as TPtrC8.
714 IMPORT_C virtual TPtrC8 WriteToBufL(CBufBase& aBuf);
717 void AddNamespaceMissingFromL(RPointerArray<CSenNamespace>& aNamespaces);
721 HBufC8* ipLocalName; // Owned
723 CBufFlat* ipContentBuf; // Owned
725 RBufWriteStream* ipContentWriteStream; // Owned
727 RPointerArray<CSenBaseAttribute>* ipAttrs; // Elements owned
729 RPointerArray<CSenElement>* ipElements; // Elements owned
731 RPointerArray<CSenNamespace>* ipNamespaces; // Elements owned
733 CSenElement* ipParent; // Not owned
735 CSenNamespace* ipNamespace; // Not Owned (deleted in upper level array)
739 #endif // SEN_XML_ELEMENT_H