/*

* Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies). 

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:        This is an optimized variant of XML element, which consumes

*                significantly less heap when compared to CSenBaseElement

*

*/

#ifndef SEN_XML_ELEMENT_H

#define SEN_XML_ELEMENT_H

//  INCLUDES

#include <s32mem.h>

#include <SenElement.h>

#include <SenNameSpace.h>

#include <SenBaseAttribute.h>

// CLASS DECLARATION

/**

*  Implementation of an XML element functionality

*  Content is stored in UTF-8 form XML. Note, that

*  setting any 8-bit content into XML without encoding

*  it into form of legal is illegal. Instead, one

*  should use encoding methods, like ones introduced 

*  in SenXmlUtils class to encode basic entities, or

*  use use some other encoding like MD5 for binary 

*  data content.

*  @lib SenXML.dll

*  @since Series60 3.1

*/

class CSenXmlElement : public CSenElement

    {

    public:  // Constructors and destructor

        /**

         *  Standard constructor.

         *  @param aLocalName   the local name for this element.

         *  Leave codes:    

         *      KErrSenInvalidCharacters if aLocalName contains illegal characters.     

         *      KErrSenZeroLengthDescriptor if aLocalName is zero length.

         */

        IMPORT_C static CSenXmlElement* NewL(const TDesC8& aLocalName);

        /**

         *  Standard constructor.

         *  @param aNsUri       the namespace URI for this element.

         *  @param aLocalName   the local name for this element.

         *  Leave codes:    

         *      KErrSenInvalidCharacters if aLocalName contains illegal characters.     

         *      KErrSenZeroLengthDescriptor if aLocalName is zero length.

         */

        IMPORT_C static CSenXmlElement* NewL(const TDesC8& aNsUri,

                                             const TDesC8& aLocalName);

        /**

         *  Standard constructor.

         *  @param aNsUri       the namespace URI for this element.

         *  @param aLocalName   the local name for this element.

         *  @param aQName       the qualified name for this element.

         *  Leave codes:    

         *      KErrSenInvalidCharacters if aLocalName or aQName contains

         *      illegal characters.     

         *      KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.

         */

        IMPORT_C static CSenXmlElement* NewL(const TDesC8& aNsUri,

                                             const TDesC8& aLocalName,

                                             const TDesC8& aQName);

        /**

         *  Standard constructor.

         *  @param aNsUri       the namespace URI for this element.

         *  @param aLocalName   the local name for this element.

         *  @param aQName       the qualified name for this element.

         *  @param apAttrs      the attributes for this element.

         *  Leave codes:    

         *      KErrSenInvalidCharacters if aLocalName or aQName contains

         *      illegal characters.     

         *      KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.

         */

        IMPORT_C static CSenXmlElement* NewL(const TDesC8& aNsUri, 

                                             const TDesC8& aLocalName,

                                             const TDesC8& aQName,

                                             const RAttributeArray& apAttrs);

        /**

         *  Standard constructor.

         *  @param aNsUri       the namespace URI for this element.

         *  @param aLocalName   the local name for this element.

         *  @param aQName       the qualified name for this element.

         *  @param apAttrs      the attributes for this element.

         *  @param aParent: the parent element for the new element

         *  Leave codes:    

         *      KErrSenInvalidCharacters if aLocalName or aQName contains

         *      illegal characters.     

         *      KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.

         */

        IMPORT_C static CSenXmlElement* NewL(const TDesC8& aNsUri,

                                             const TDesC8& aLocalName,

                                             const TDesC8& aQName,

                                             const RAttributeArray& apAttrs,

                                             CSenElement& aParent);

        /**

        * Destructor.

        */

        IMPORT_C virtual ~CSenXmlElement();

    public: // New functions

        /**

         *  Adds attributes to the element. Calls internally AddAttributesL()

         *  Can be overridden to replace old attributes.

         *  @param  aAttrs: the array of attributes.

         */

        IMPORT_C virtual void SetAttributesL(const RAttributeArray& apAttrs);

        // Functions from base classes

        // From CSenElement

        /**

        *   Getter for Element's local name.

        *   @return Localname or KNullDesC if not set.

        */  

        IMPORT_C virtual const TDesC8& LocalName() const;

        /**

        *   Getter for Element's namespace URI.

        *   @return Namespace URI or KNullDesC if not set.

        */

        IMPORT_C virtual const TDesC8& NamespaceURI() const;

        /**

         *  Getter for namespace prefix of this element.

         *  @return namespace prefix or KNullDesC if not set.

         */

        IMPORT_C virtual const TDesC8& NsPrefix() const;

        /**

         *  Setter for namespace prefix of this element.

         *  @param aPrefix: new namespace prefix for the element.

         */

        IMPORT_C virtual void SetPrefixL(const TDesC8& aPrefix);

        /**

         *  Method for checking if the element has any content within.

         *  @return ETrue if has content, EFalse if not.

         */

        IMPORT_C virtual TBool HasContent() const;

        /**

         *  Getter for the content of the element.

         *  @return the content or KNullDesC if empty.

         */

        IMPORT_C virtual TPtrC8 Content() const;

        /**

         *  Getter for the content of the element, unicode version.

         *  @return content as unicode. Ownership IS TRANSFERRED to the caller.

         */

        IMPORT_C virtual HBufC* ContentUnicodeL() const;

        /**

         *  Sets the content to the element. Old content is overwritten.

         *  @param  aContent:   The content to be set. Can be KNullDesC8.

         *  @return The content of the element or KNullDesC8 if no content was set.

         */

        IMPORT_C virtual TPtrC8 SetContentL(const TDesC8& aContent);

        /**

         *  Gets the write stream for the content for easy appending.

         *  Writing 8-bit (UTF-8) string to the returned stream will be appended

         *  to the content.

         *  @return reference to the RWriteStream.

         */

        IMPORT_C virtual RWriteStream& ContentWriteStreamL();

        /**

         * Checks if element matches to another element

         * by its content and child elements. Element

         * can contain more data than the given pattern.

         * @since Series60 3.0

         * @param aCandidate    The pattern to be matched. Must contain same or 

         *                  less data for match to come true.

         * @return ETrue if content and possible children match exactly 

         *          to given pattern. EFalse otherwise.

         */

        IMPORT_C virtual TBool ConsistsOfL(MSenElement& aCandidate);

        /**

        *   Setter for Element's namespace URI.

        *   @param aNsUri:  Namespace URI

        */

        IMPORT_C virtual void SetNamespaceL(const TDesC8& aNsUri);

        /**

        *   Setter for Element's namespace URI.

        *   @param aNsPrefix:   Namespace prefix

        *   @param aNsUri:      Namespace URI

        */

        IMPORT_C virtual void SetNamespaceL(const TDesC8& aNsPrefix,

                                            const TDesC8& aNsUri);

        /**

         * Adds a namespace declaration.

         * If this element (or its parent if parameter aCheckInParent is ETrue) 

         * already has a Namespace with the same prefix and URI the given

         * Namespace is not added.

         * @param aNewNamespace

         * @param aCheckInParent

         * @return the added Namespace, or the equivalent pre-existing one.

         */ 

        IMPORT_C virtual const CSenNamespace* AddNamespaceL(CSenNamespace& aNewNamespace,

                                                            TBool aCheckInParent);

        /**

        *   Method for adding a namespace for the Element.

        *   @param aPrefix: Namespace prefix

        *   @param aUri:    Namespace URI

        *   @return the added Namespace, or the equivalent pre-existing one.

        */

        IMPORT_C virtual const CSenNamespace* AddNamespaceL(const TDesC8& aPrefix,

                                                            const TDesC8& aUri);

        /**

        *   Getter for Element's namespace.

        *   @return const pointer to the CSenNamespace object of this Element.

        *           NULL if not set.

        */ 

        IMPORT_C virtual const CSenNamespace* Namespace();

        /**

         * Getter for new namespace, using a namespace prefix as a search criteria.

         * @param aNsPrefix is the new namespace prefix for this element

         * @return the found Namespace that is declared for the given prefix

         * within the scope of this Element. If no such prefix is

         * declared return null.

         */     

        IMPORT_C virtual const CSenNamespace* Namespace(const TDesC8& aNsPrefix);

        /**

         * Getter for new namespace, using a namespace prefix as a search criteria,

         * supporting both normal and recursive search mode (checking the parent).

         * @param aNsPrefix:        The prefix used to search

         * @param aCheckInParent:   The flag indicating whether to check parent's

         *                          namespaces too if not found in the current 

         *                          element. 

         *                          ETrue to check, EFalse for not to check.

         * @return the found Namespace that is declared for the given prefix 

         *                   and namespace URI within the scope of this Element

         *                   or NULL if not found

         */ 

        IMPORT_C virtual const CSenNamespace* Namespace(const TDesC8& aNsPrefix,

                                                        const TBool aCheckInParent);

        /**

         * Getter for new namespace, using both namespace prefix and namespace URI as search criteria.

         * @param aNsPrefix:    The prefix used to search

         * @param aUri:         The namespace URI used to search.

         * @return the found Namespace that is declared for the given prefix 

         *                   and namespace URI within the scope of this Element

         *                   or NULL if not found.

         */     

        IMPORT_C virtual const CSenNamespace* Namespace(const TDesC8& aNsPrefix,

                                                        const TDesC8& aUri);

        /**

         *  Getting the child elements of this element matching the given criteria.

         *  @param aElementArray:   Array to be filled with the matching elements,

         *                          or empty array if no matching found. 

         *                          Any modifications made on the returned items

         *                          modify the real childs too.

         *  @param aNsUri:          namespace URI to be matched

         *  @param aLocalName:      local name to be matched

         *  @return KErrNone        ok

         *          KErrNotFound    No child elements exist.

         */     

        IMPORT_C virtual TInt ElementsL(RPointerArray<CSenElement>& aElementArray,

                                        const TDesC8& aNsUri,

                                        const TDesC8& aLocalName);

        /**

         *  Getting the child elements of this element matching the given criteria.

         *  @param aElementArray:   Array to be filled with the matching elements,

         *                          or empty array if no matching found. 

         *                          Any modifications made on the returned items

         *                          modify the real childs too.

         *  @param aNsUri:          namespace URI to be matched

         *  @param aLocalName:      local name to be matched

         *  @return KErrNone        ok

         *          KErrNotFound    No child elements exist.

         */     

        IMPORT_C virtual TInt ElementsL(RPointerArray<CSenElement>& aElementArray,

                                        const TDesC8& aLocalName);

        /**

         *  Getting the child elements of this element.

         *  @return an array of child elements. This is an empty array if there

         *          are no children. Any modifications made on the returned array

         *          modify the element object.

         */     

        IMPORT_C virtual RPointerArray<CSenElement>& ElementsL();

        /**

         *  Gets all the attributes of this element in an array.

         *  @return array of attributes. Array will be empty if element has 

         *          no attributes.

         */     

        IMPORT_C virtual RPointerArray<CSenBaseAttribute>& AttributesL();

        /**

         *  Gets all the namespaces of this element in an array.

         *  @return array of namespaces. Array will be empty if element has 

         *          no namespaces.

         */     

        IMPORT_C virtual RPointerArray<CSenNamespace>& NamespacesL();

        /**

         *  Gets the value of the given attribute.

         *  @param aName:   Name of the attribute in question.

         *  @return the value of the attribute, or NULL if not found. Ownership is

         *          NOT TRANSFERRED.

         */     

        IMPORT_C virtual const TDesC8* AttrValue(const TDesC8& aName);

        /**

         *  Adds an attribute. If attribute is already existing, 

         *  the value of the attribute will be replaced.

         */

        IMPORT_C virtual void AddAttrL(const TDesC8& aName, const TDesC8& aValue);

        /**

         *  Gets the parent element of this element.

         *  @return the parent element or NULL if no parent set. 

         *          Ownership is NOT transferred to the caller.

         */     

        IMPORT_C virtual CSenElement* Parent();

        /**

         *  Sets the parent element to this element. Notice that the element is not

         *  automatically added as a child of the parent. Parent's 

         *  AddElementL() should be called instead.

         *  @param apParent:    The wanted parent. Can be NULL.

         *  @return the parent element

         */ 

        IMPORT_C virtual CSenElement* SetParent(CSenElement* apParent);

        /**

         *  Gets the root element. If no parent element, returns this element.

         *  @return the root of the tree. Ownership is NOT transferred.

         */     

        IMPORT_C virtual MSenElement& Root();

        /**

         *  Gets the child element with the specified local name.

         *  Assumes that namespace is the same as this parent element.

         *  @return the child element or NULL if the child with the specified 

         *          local name is not found. Ownership is NOT transferred.

         */ 

        IMPORT_C virtual CSenElement* Element(const TDesC8& aLocalName);

        /**

         *  Gets the child element with the specified local name and namespace URI.

         *  @return the child element or NULL if the child with the specified 

         *          criterias is not found. Ownership is NOT transferred.

         */ 

        IMPORT_C virtual CSenElement* Element(const TDesC8& aNsUri,

                                              const TDesC8& aLocalName);

        /**

         * Create a new element ready for adding or insertion.

         * If the given namespace prefix is not declared yet

         * the element will not be created and NULL will be returned.

         * @param aNsPrefix:    The namespace prefix

         * @param aLocalName:   The new elements localname

         * @return  the new Element just created, or NULL if given prefix was not

         *          declared yet. Ownership is transferred to the caller.

         *  Leave codes:    

         *      KErrSenInvalidCharacters if aLocalName contains illegal characters.     

         *      KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.

         */     

        IMPORT_C virtual CSenElement* CreateElementL(const TDesC8& aNsPrefix,

                                                     const TDesC8& aLocalName);

        /**

         * Insert an Element into the list of children elements

         * so that the inserted Element is placed right before the aBeforeElement.

         * If aBeforeElement is not found, element will be appended to the last

         * position.

         * Function leaves if error occurs in inserting.

         * @param aInsertedElement: the element to be inserted. 

         *                          Ownership is transferred.

         * @param aBeforeElement:   the element which will be right next to the 

         *                          element just inserted.

         * @return the inserted Element

         */     

        IMPORT_C virtual CSenElement& InsertElementL(CSenElement& aElement,

                                                     const CSenElement& aBeforeElement);

        /**

         * Adds an Element to the children elements. 

         * Sets this element to be the new parent of the given element.

         * @param aElement: the element to be added. Ownership is transferred.

         * @return the added Element

         */ 

        IMPORT_C virtual CSenElement& AddElementL(CSenElement& aElement);

        /**

         * Constructs and adds a new element to the children elements. 

         * Sets this element to be the new parent of the given element.

         * @param aNsUri:       namespace URI of the new element

         * @param aLocalName:   local name of the new element

         * @return the added Element

         *  Leave codes:    

         *      KErrSenInvalidCharacters if aLocalName contains illegal characters.     

         *      KErrSenZeroLengthDescriptor if aLocalName is zero length.

         */     

        IMPORT_C virtual CSenElement& AddElementL(const TDesC8& aNsUri,

                                                  const TDesC8& aLocalName);

        /**

         * Constructs and adds a new element to the children elements. 

         * Sets this element to be the new parent of the given element.

         * @param aNsUri:       namespace URI of the new element

         * @param aLocalName:   local name of the new element

         * @param aQName:       qualified name of the new element

         * @return the added Element

         *  Leave codes:    

         *      KErrSenInvalidCharacters if aLocalName or aQName contain illegal 

         *      characters.     

         *      KErrSenZeroLengthDescriptor if aLocalName or aQName is zero length.

         */ 

        IMPORT_C virtual CSenElement& AddElementL(const TDesC8& aNsUri,

                                                  const TDesC8& aLocalName,

                                                  const TDesC8& aQName);

        /**

         * Constructs and adds a new element to the children elements. 

         * Sets this element to be the new parent of the given element.

         * Note: Element is created with no specific namespace, default namespace

         * of some of the upper level elements are in effect if there is such a 

         * namespace.

         * @param aLocalName:   local name of the new element

         * @return the added Element

         *  Leave codes:    

         *      KErrSenInvalidCharacters if aLocalName contains illegal characters.     

         *      KErrSenZeroLengthDescriptor if aLocalName is zero length.

         */     

        IMPORT_C virtual CSenElement& AddElementL(const TDesC8& aLocalName);

        /**

         *  Remove an element from the childs.

         *  @param  aElement:   the element to be removed.

         *  @return The removed element. May be NULL if nothing was removed

         *          (if element was not found from the childs).

         *          The caller TAKES OWNERSHIP of the removed element.

         */     

        IMPORT_C virtual CSenElement* RemoveElement(CSenElement& aElement);

        /**

         *  Remove an element from the childs.

         *  @param  aNsUri:     the namespace URI of the element to be removed.

         *  @param  aLocalName: the local name of the element to be removed.

         *  @return The removed element. May be NULL if nothing was removed

         *          (if element was not found from the childs).

         *          The caller TAKES OWNERSHIP of the removed element.

         */     

        IMPORT_C virtual CSenElement* RemoveElement(const TDesC8& aNsUri,

                                                    const TDesC8& aLocalName);

        /**

         *  Remove an element from the childs.

         *  @param  aLocalName: the local name of the element to be removed.

         *  @return The removed element. May be NULL if nothing was removed

         *          (if element was not found from the childs).

         *          The caller TAKES OWNERSHIP of the removed element.

         */     

        IMPORT_C virtual CSenElement* RemoveElement(const TDesC8& aLocalName);

        /**

         *  Replaces an element from the childs with another element. 

         *  Element's local name and namespace URI will be used to match the

         *  element to be replaced. If matching element is not found, will

         *  normally add the given element to the childs.

         *  @param  aElement:   the element to be added. Ownership is transferred.

         *  @return The old element. May be NULL if nothing was replaced

         *          (if element was not found from the childs).

         *          The caller TAKES OWNERSHIP of the old element.

         */ 

        IMPORT_C virtual CSenElement* ReplaceElementL(CSenElement& aElement);

        /**

         *  Gets the element as an XML buffer. Buffer will contain all the childs

         *  @return element as XML. Caller takes ownership.

         */

        IMPORT_C virtual HBufC8* AsXmlL();

        /**

         *  Gets the element as an unicode XML buffer. 

         *  Buffer will contain all the childs etc.

         *  @return element as XML. Caller takes ownership.

         */     

        IMPORT_C virtual HBufC* AsXmlUnicodeL();

        /**

         *  Element writes itself to a write stream using UTF-8 charset encoding.

         *  @param aWriteStream:    The stream to write to.

         */     

        IMPORT_C virtual void WriteAsXMLToL(RWriteStream& aWriteStream);

        /**

         *  Element writes its namespaces to a write stream using UTF-8 charset 

         *  encoding.