2 * Copyright (c) 2002-2005 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: Implementation of an XML element functionality
25 #ifndef SEN_BASE_ELEMENT_H
26 #define SEN_BASE_ELEMENT_H
30 #include <SenElement.h>
31 #include <SenNameSpace.h>
32 #include <SenBaseAttribute.h>
37 * Implementation of an XML element functionality
38 * Content is stored in UTF-8 form XML. Note, that
39 * setting any 8-bit content into XML without encoding
40 * it into form of legal is illegal. Instead, one
41 * should use encoding methods, like ones introduced
42 * in SenXmlUtils class to encode basic entities, or
43 * use use some other encoding like MD5 for binary
48 class CSenBaseElement : public CSenElement
50 public: // Constructors and destructor
53 * Standard constructor.
54 * @param aLocalName the local name for this element.
56 * KErrSenInvalidCharacters if aLocalName contains illegal characters.
57 * KErrSenZeroLengthDescriptor if aLocalName is zero length.
60 IMPORT_C static CSenBaseElement* NewL(const TDesC8& aLocalName);
62 * Standard constructor.
63 * @param aNsUri the namespace URI for this element.
64 * @param aLocalName the local name for this element.
66 * KErrSenInvalidCharacters if aLocalName contains illegal characters.
67 * KErrSenZeroLengthDescriptor if aLocalName is zero length.
69 IMPORT_C static CSenBaseElement* NewL(const TDesC8& aNsUri,
70 const TDesC8& aLocalName);
73 * Standard constructor.
74 * @param aNsUri the namespace URI for this element.
75 * @param aLocalName the local name for this element.
76 * @param aQName the qualified name for this element.
78 * KErrSenInvalidCharacters if aLocalName or aQName contains
80 * KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
82 IMPORT_C static CSenBaseElement* NewL(const TDesC8& aNsUri,
83 const TDesC8& aLocalName,
84 const TDesC8& aQName);
87 * Standard constructor.
88 * @param aNsUri the namespace URI for this element.
89 * @param aLocalName the local name for this element.
90 * @param aQName the qualified name for this element.
91 * @param apAttrs the attributes for this element.
93 * KErrSenInvalidCharacters if aLocalName or aQName contains
95 * KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
97 IMPORT_C static CSenBaseElement* NewL(const TDesC8& aNsUri,
98 const TDesC8& aLocalName,
100 const RAttributeArray& apAttrs);
103 * Standard constructor.
104 * @param aNsUri the namespace URI for this element.
105 * @param aLocalName the local name for this element.
106 * @param aQName the qualified name for this element.
107 * @param apAttrs the attributes for this element.
108 * @param aParent: the parent element for the new element
110 * KErrSenInvalidCharacters if aLocalName or aQName contains
111 * illegal characters.
112 * KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
114 IMPORT_C static CSenBaseElement* NewL(const TDesC8& aNsUri,
115 const TDesC8& aLocalName,
116 const TDesC8& aQName,
117 const RAttributeArray& apAttrs,
118 CSenElement& aParent);
123 IMPORT_C virtual ~CSenBaseElement();
128 * Adds attributes to the element. Calls internally AddAttributesL()
129 * Can be overridden to replace old attributes.
130 * @param aAttrs: the array of attributes.
132 IMPORT_C virtual void SetAttributesL(const RAttributeArray& apAttrs);
134 // Functions from base classes
139 * Getter for Element's local name.
140 * @return Localname or KNullDesC if not set.
142 IMPORT_C virtual const TDesC8& LocalName() const;
145 * Getter for Element's namespace URI.
146 * @return Namespace URI or KNullDesC if not set.
148 IMPORT_C virtual const TDesC8& NamespaceURI() const;
151 * Getter for namespace prefix of this element.
152 * @return namespace prefix or KNullDesC if not set.
154 IMPORT_C virtual const TDesC8& NsPrefix() const;
157 * Setter for namespace prefix of this element.
158 * @param aPrefix: new namespace prefix for the element.
160 IMPORT_C virtual void SetPrefixL(const TDesC8& aPrefix);
163 * Method for checking if the element has any content within.
164 * @return ETrue if has content, EFalse if not.
166 IMPORT_C virtual TBool HasContent() const;
169 * Getter for the content of the element.
170 * @return the content or KNullDesC if empty.
172 IMPORT_C virtual TPtrC8 Content() const;
175 * Getter for the content of the element, unicode version.
176 * @return content as unicode. Ownership IS TRANSFERRED to the caller.
178 IMPORT_C virtual HBufC* ContentUnicodeL() const;
181 * Sets the content to the element. Old content is overwritten.
182 * @param aContent: The content to be set. Can be KNullDesC8.
183 * @return The content of the element or KNullDesC8 if no content was set.
185 IMPORT_C virtual TPtrC8 SetContentL(const TDesC8& aContent);
188 * Gets the write stream for the content for easy appending.
189 * Writing 8-bit (UTF-8) string to the returned stream will be appended
191 * @return reference to the RWriteStream.
193 IMPORT_C virtual RWriteStream& ContentWriteStreamL();
196 * Checks if element matches to another element
197 * by its content and child elements. Element
198 * can contain more data than the given pattern.
199 * @since Series60 3.0
200 * @param aCandidate The pattern to be matched. Must contain same or
201 * less data for match to come true.
202 * @return ETrue if content and possible children match exactly
203 * to given pattern. EFalse otherwise.
205 IMPORT_C virtual TBool ConsistsOfL(MSenElement& aCandidate);
208 * Setter for Element's namespace URI.
209 * @param aNsUri: Namespace URI
211 IMPORT_C virtual void SetNamespaceL(const TDesC8& aNsUri);
214 * Setter for Element's namespace URI.
215 * @param aNsPrefix: Namespace prefix
216 * @param aNsUri: Namespace URI
218 IMPORT_C virtual void SetNamespaceL(const TDesC8& aNsPrefix,
219 const TDesC8& aNsUri);
222 * Adds a namespace declaration.
223 * If this element (or its parent if parameter aCheckInParent is ETrue)
224 * already has a Namespace with the same prefix and URI the given
225 * Namespace is not added.
226 * @param aNewNamespace
227 * @param aCheckInParent
228 * @return the added Namespace, or the equivalent pre-existing one.
230 IMPORT_C virtual const CSenNamespace* AddNamespaceL(
231 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();
250 * @return the found Namespace that is declared for the given prefix
251 * within the scope of this Element. If no such prefix is
252 * declared return null.
254 IMPORT_C virtual const CSenNamespace* Namespace(const TDesC8& aNsPrefix);
257 * @param aNsPrefix: The prefix used to search
258 * @param aCheckInParent: The flag indicating whether to check parent's
259 * namespaces too if not found in the current
261 * ETrue to check, EFalse for not to check.
262 * @return the found Namespace that is declared for the given prefix
263 * and namespace URI within the scope of this Element
264 * or NULL if not found
266 IMPORT_C virtual const CSenNamespace* Namespace(const TDesC8& aNsPrefix,
267 const TBool aCheckInParent);
270 * @param aNsPrefix: The prefix used to search
271 * @param aUri: The namespace URI used to search.
272 * @return the found Namespace that is declared for the given prefix
273 * and namespace URI within the scope of this Element
274 * or NULL if not found.
276 IMPORT_C virtual const CSenNamespace* Namespace(const TDesC8& aNsPrefix,
280 * Getting the child elements of this element matching the given criteria.
281 * @param aElementArray: Array to be filled with the matching elements,
282 * or empty array if no matching found.
283 * Any modifications made on the returned items
284 * modify the real childs too.
285 * @param aNsUri: namespace URI to be matched
286 * @param aLocalName: local name to be matched
287 * @return KErrNone ok
288 * KErrNotFound No child elements exist.
290 IMPORT_C virtual TInt ElementsL(RPointerArray<CSenElement>& aElementArray,
291 const TDesC8& aNsUri,
292 const TDesC8& aLocalName);
295 * Getting the child elements of this element matching the given criteria.
296 * @param aElementArray: Array to be filled with the matching elements,
297 * or empty array if no matching found.
298 * Any modifications made on the returned items
299 * modify the real childs too.
300 * @param aNsUri: namespace URI to be matched
301 * @param aLocalName: local name to be matched
302 * @return KErrNone ok
303 * KErrNotFound No child elements exist.
305 IMPORT_C virtual TInt ElementsL(RPointerArray<CSenElement>& aElementArray,
306 const TDesC8& aLocalName);
309 * Getting the child elements of this element.
310 * @return an array of child elements. This is an empty array if there
311 * are no children. Any modifications made on the returned array
312 * modify the element object.
314 IMPORT_C virtual RPointerArray<CSenElement>& ElementsL();
317 * Gets all the attributes of this element in an array.
318 * @return array of attributes. Array will be empty if element has
321 IMPORT_C virtual RPointerArray<CSenBaseAttribute>& AttributesL();
324 * Gets all the namespaces of this element in an array.
325 * @return array of namespaces. Array will be empty if element has
328 IMPORT_C virtual RPointerArray<CSenNamespace>& NamespacesL();
331 * Gets the value of the given attribute.
332 * @param aName: Name of the attribute in question.
333 * @return the value of the attribute, or NULL if not found. Ownership is
336 IMPORT_C virtual const TDesC8* AttrValue(const TDesC8& aName);
339 * Adds an attribute. If attribute is already existing,
340 * the value of the attribute will be replaced.
342 IMPORT_C virtual void AddAttrL(const TDesC8& aName, const TDesC8& aValue);
345 * Gets the parent element of this element.
346 * @return the parent element or NULL if no parent set.
347 * Ownership is NOT transferred to the caller.
349 IMPORT_C virtual CSenElement* Parent();
352 * Sets the parent element to this element. Notice that the element is not
353 * automatically added as a child of the parent. Parent's
354 * AddElementL() should be called instead.
355 * @param apParent: The wanted parent. Can be NULL.
356 * @return the parent element
358 IMPORT_C virtual CSenElement* SetParent(CSenElement* apParent);
361 * Gets the root element. If no parent element, returns this element.
362 * @return the root of the tree. Ownership is NOT transferred.
364 IMPORT_C virtual MSenElement& Root();
367 * Gets the child element with the specified local name.
368 * Assumes that namespace is the same as this parent element.
369 * @return the child element or NULL if the child with the specified
370 * local name is not found. Ownership is NOT transferred.
372 IMPORT_C virtual CSenElement* Element(const TDesC8& aLocalName);
375 * Gets the child element with the specified local name and namespace URI.
376 * @return the child element or NULL if the child with the specified
377 * criterias is not found. Ownership is NOT transferred.
379 IMPORT_C virtual CSenElement* Element( const TDesC8& aNsUri,
380 const TDesC8& aLocalName);
383 * Create a new element ready for adding or insertion.
384 * If the given namespace prefix is not declared yet
385 * the element will not be created and NULL will be returned.
386 * @param aNsPrefix: The namespace prefix
387 * @param aLocalName: The new elements localname
388 * @return the new Element just created, or NULL if given prefix was not
389 * declared yet. Ownership is transferred to the caller.
391 * KErrSenInvalidCharacters if aLocalName contains illegal characters.
392 * KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
394 IMPORT_C virtual CSenElement* CreateElementL(const TDesC8& aNsPrefix,
395 const TDesC8& aLocalName);
398 * Insert an Element into the list of children elements
399 * so that the inserted Element is placed right before the aBeforeElement.
400 * If aBeforeElement is not found, element will be appended to the last
402 * Function leaves if error occurs in inserting.
403 * @param aInsertedElement: the element to be inserted.
404 * Ownership is transferred.
405 * @param aBeforeElement: the element which will be right next to the
406 * element just inserted.
407 * @return the inserted Element
409 IMPORT_C virtual CSenElement& InsertElementL(CSenElement& aElement,
410 const CSenElement& aBeforeElement);
413 * Adds an Element to the children elements.
414 * Sets this element to be the new parent of the given element.
415 * @param aElement: the element to be added. Ownership is transferred.
416 * @return the added Element
418 IMPORT_C virtual CSenElement& AddElementL(CSenElement& aElement);
421 * Constructs and adds a new element to the children elements.
422 * Sets this element to be the new parent of the given element.
423 * @param aNsUri: namespace URI of the new element
424 * @param aLocalName: local name of the new element
425 * @return the added Element
427 * KErrSenInvalidCharacters if aLocalName contains illegal characters.
428 * KErrSenZeroLengthDescriptor if aLocalName is zero length.
430 IMPORT_C virtual CSenElement& AddElementL( const TDesC8& aNsUri,
431 const TDesC8& aLocalName);
434 * Constructs and adds a new element to the children elements.
435 * Sets this element to be the new parent of the given element.
436 * @param aNsUri: namespace URI of the new element
437 * @param aLocalName: local name of the new element
438 * @param aQName: qualified name of the new element
439 * @return the added Element
441 * KErrSenInvalidCharacters if aLocalName or aQName contain illegal
443 * KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
445 IMPORT_C virtual CSenElement& AddElementL(const TDesC8& aNsUri,
446 const TDesC8& aLocalName,
447 const TDesC8& aQName);
450 * Constructs and adds a new element to the children elements.
451 * Sets this element to be the new parent of the given element.
452 * Note: Element is created with no specific namespace, default namespace
453 * of some of the upper level elements are in effect if there is such a
455 * @param aLocalName: local name of the new element
456 * @return the added Element
458 * KErrSenInvalidCharacters if aLocalName contains illegal characters.
459 * KErrSenZeroLengthDescriptor if aLocalName is zero length.
461 IMPORT_C virtual CSenElement& AddElementL(const TDesC8& aLocalName);
464 * Remove an element from the childs.
465 * @param aElement: the element to be removed.
466 * @return The removed element. May be NULL if nothing was removed
467 * (if element was not found from the childs).
468 * The caller TAKES OWNERSHIP of the removed element.
470 IMPORT_C virtual CSenElement* RemoveElement(CSenElement& aElement);
473 * Remove an element from the childs.
474 * @param aNsUri: the namespace URI of the element to be removed.
475 * @param aLocalName: the local name of the element to be removed.
476 * @return The removed element. May be NULL if nothing was removed
477 * (if element was not found from the childs).
478 * The caller TAKES OWNERSHIP of the removed element.
480 IMPORT_C virtual CSenElement* RemoveElement(const TDesC8& aNsUri,
481 const TDesC8& aLocalName);
484 * Remove an element from the childs.
485 * @param aLocalName: the local name of the element to be removed.
486 * @return The removed element. May be NULL if nothing was removed
487 * (if element was not found from the childs).
488 * The caller TAKES OWNERSHIP of the removed element.
490 IMPORT_C virtual CSenElement* RemoveElement(const TDesC8& aLocalName);
493 * Replaces an element from the childs with another element.
494 * Element's local name and namespace URI will be used to match the
495 * element to be replaced. If matching element is not found, will
496 * normally add the given element to the childs.
497 * @param aElement: the element to be added. Ownership is transferred.
498 * @return The old element. May be NULL if nothing was replaced
499 * (if element was not found from the childs).
500 * The caller TAKES OWNERSHIP of the old element.
502 IMPORT_C virtual CSenElement* ReplaceElementL(CSenElement& aElement);
505 * Gets the element as an XML buffer. Buffer will contain all the childs
506 * @return element as XML. Caller takes ownership.
508 IMPORT_C virtual HBufC8* AsXmlL();
511 * Gets the element as an unicode XML buffer.
512 * Buffer will contain all the childs etc.
513 * @return element as XML. Caller takes ownership.
515 IMPORT_C virtual HBufC* AsXmlUnicodeL();
518 * Element writes itself to a write stream using UTF-8 charset encoding.
519 * @param aWriteStream: The stream to write to.
521 IMPORT_C virtual void WriteAsXMLToL(RWriteStream& aWriteStream);
524 * Element writes its namespaces to a write stream using UTF-8 charset
526 * @param aWriteStream: The stream to write to.
528 IMPORT_C virtual void WriteNamespacesToL(RWriteStream& aWriteStream);
531 * Gets the current element as XML element. Mostly used to get the
532 * classes which implement this interface as an instance of this
534 * @return the current object as element. Ownership is NOT transferred.
536 IMPORT_C virtual MSenElement* AsElement();
539 * Copies content from given element to this element appending to the
540 * existing content if there is any.
541 * @param aSource: The source element.
543 IMPORT_C void CopyFromL(CSenElement& aSource);
546 * Detach the element from its parent.
547 * If the element, or one of its children, is dependent
548 * on a namespace declared in the scope of the parent
549 * copy those namespace declarations to this element.
550 * @return this Element. Ownership IS TRANSFERRED to the caller.
552 IMPORT_C virtual CSenElement* DetachL();
555 * Gets a child element from a specified index.
556 * @param aIndex: the index what to get
557 * @return child element from a current index. NULL if no child in given
560 IMPORT_C virtual CSenElement* Child(TInt aIndex);
563 * (Re-) Set the name and namespace of this Element. The element will be
564 * given the localName in the the given namespace. A prefix will be
565 * computed from the qualified name.
566 * This method should be used with care and is mainly intended for
567 * protected use in implementations.
568 * @param aNamespaceURI: The new namespace URI.
569 * @param aLocalName: The new local name.
570 * @param aQName: The new qualified name.
572 IMPORT_C virtual void Set(const TDesC8& aNsUri,
573 const TDesC8& aLocalName,
574 const TDesC8& aQName);
577 * Adds new attributes to the element.
578 * @param aAttrs: the array of attributes.
580 IMPORT_C virtual void AddAttributesL(const RAttributeArray& apAttrs);
585 * C++ default constructor.
587 IMPORT_C CSenBaseElement();
590 * Following BaseConstructL methods should be called from the deriving
591 * classes ConstructL() methods. Parameter info is found in the
592 * corresponding NewL-methods.
594 IMPORT_C void BaseConstructL( const TDesC8& aLocalName);
596 IMPORT_C void BaseConstructL( const TDesC8& aNsUri,
597 const TDesC8& aLocalName);
599 IMPORT_C void BaseConstructL( const TDesC8& aNsUri,
600 const TDesC8& aLocalName,
601 const TDesC8& aQName);
603 IMPORT_C void BaseConstructL( const TDesC8& aNsUri,
604 const TDesC8& aLocalName,
605 const TDesC8& aQName,
606 const RAttributeArray& apAttrs);
608 IMPORT_C void BaseConstructL( const TDesC8& aNsUri,
609 const TDesC8& aLocalName,
610 const TDesC8& aQName,
611 const RAttributeArray& apAttrs,
612 CSenElement& aParent);
617 * Method for finding an attribute with given name.
618 * @param aName a name of the attribute to be searched for
619 * @return the 1st attribute with the name, or NULL.
620 * Ownership is not transferred.
622 IMPORT_C virtual CSenBaseAttribute* FindAttr(const TDesC8& aName);
625 * Method for finding index for a wanted element.
626 * @param aNsUri a namespace URI which needs to match
627 * @param aLocalName a local name which needs to match
628 * @return Index of the element with given characteristics.
629 * or KErrNotFound if none matching
631 IMPORT_C virtual TInt IndexOfElement(const TDesC8& aNsUri,
632 const TDesC8& aLocalName) const;
635 * Writes element's attributes into a writestream.
636 * @param aWriteStream writestream to write into
638 IMPORT_C virtual void WriteAttrsToL(RWriteStream& aWriteStream);
641 * Helper function to write an attribute into a writestream.
642 * @param aWriteStream writestream to write into
643 * @param aName attribute name
644 * @param aValue attribute value
646 IMPORT_C virtual void WriteAttrToL(RWriteStream& aWriteStream,
648 const TDesC8& aValue);
651 * Writes all internal elements into a writestream.
652 * @param aWriteStream writestream to write into
654 IMPORT_C virtual void WriteElementsToL(RWriteStream& aWriteStream);
657 * Writes all element's content into a writestream.
658 * @param aWriteStream writestream to write into
660 IMPORT_C virtual void WriteContentToL(RWriteStream& aWriteStream);
663 * Adds an attribute into this element. Used also adding new namespaces
665 * @param aQName Attribute's qualified name
666 * @param aLocalName Attribute's local name
667 * @param aValue Attribute's value
668 * @return value of the attribute as string (TDesC&)
670 * KErrSenInvalidCharacters if aLocalName or aQName contain illegal
672 * KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.
674 IMPORT_C virtual const TDesC8& AddAttributeL(const TDesC8& aQName,
675 const TDesC8& aLocalName,
676 const TDesC8& aValue);
679 * Adds an attribute into this element. Used also adding new namespaces
681 * @param aLocalName Attribute's local name
682 * @param aValue Attribute's value
683 * @return value of the attribute as string (TDesC&)
685 * KErrSenInvalidCharacters if aLocalName contains illegal characters.
686 * KErrSenZeroLengthDescriptor if aAttrName is zero length, or
687 * if the local name part of it is zero length.
689 IMPORT_C virtual const TDesC8& AddAttributeL(const TDesC8& aAttrName,
690 const TDesC8& aValue);
693 * Adds an attribute into this element.
694 * @param apAttribute Attribute to be added. Ownership is transferred
696 * @return attribute value as a string (TDesC8&)
698 IMPORT_C const TDesC8& AddAttributeL(CSenBaseAttribute* apAttribute);
701 * Allocates a new buffer for saving content, if none allocated yet.
703 IMPORT_C virtual void AllocContentBufL();
706 * Writes element into a dynamic buffer.
707 * @param aBuf a dynamic buffer where to append everything.
708 * @return the modified buffer as TPtrC8.
710 IMPORT_C virtual TPtrC8 WriteToBufL(CBufBase& aBuf);
712 private: // New functions
714 void AddNamespaceMissingFromL(RPointerArray<CSenNamespace>& aNamespaces);
717 HBufC8* ipLocalName; // Owned
718 HBufC8* iNotUsed; // Not used (kept for binary compatibility)
719 CBufFlat* ipContentBuf; // Owned
720 RBufWriteStream iContentWriteStream;
721 RPointerArray<CSenBaseAttribute> iAttrs; // Elements owned
722 RPointerArray<CSenElement> iElements; // Elements owned
723 RPointerArray<CSenNamespace> iNamespaces; // Elements owned
724 CSenElement* ipParent; // Not owned
725 CSenNamespace* ipNamespace; // Not Owned (deleted in upper level array)
728 #endif // SEN_BASE_ELEMENT_H