/*
* Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies). 
* All rights reserved.
* This component and the accompanying materials are made available
* 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
* which accompanies this distribution, and is available
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:        Central place for debug-type macros
*
*/








#ifndef SEN_ELEMENT_H
#define SEN_ELEMENT_H

//  INCLUDES
#include <e32base.h>
#include <s32strm.h>
#include <xml/Attribute.h>
#include <stringpool.h>

#include <MSenElement.h>

using namespace Xml;

// CLASS DECLARATION

/**
*  Abstract class definition of XML element
*  @lib SenXML.dll
*  @since Series60 3.0
*/
class CSenElement : public CBase, public MSenElement
    {
    public: // Functions from base classes

        // From MSenElement 
        
        /**
        * Getter for local name.
        * @since Series60 3.0
        * @return KNullDesC if not set (argumentless constructor).
        */
        virtual const TDesC8& LocalName() const = 0;

        /**
        * Getter for namespace URI.
        * @since Series60 3.0
        * @return KNullDesC if not set.
        */      
        virtual const TDesC8& NamespaceURI() const = 0;

        /**
        * Setter for Element's namespace URI.
        * @since Series60 3.0
        * @param @param aNsUri: Namespace URI
        */      
        virtual void SetNamespaceL(const TDesC8& aNsUri) = 0;

        /**
        * Setter for Element's namespace URI.
        * @since Series60 3.0
        * @param aNsPrefix: Namespace prefix
        * @param aNsUri:        Namespace URI
        */      
        virtual void SetNamespaceL( const TDesC8& aNsPrefix,
                                    const TDesC8& aNsUri) = 0;

        /**
        * Method for adding a namespace for the Element.
        * @since Series60 3.0
        * @param aPrefix:   Namespace prefix
        * @param aUri:  Namespace URI
        * @return the added Namespace, or the equivalent pre-existing one.
        */      
        virtual const CSenNamespace* AddNamespaceL( const TDesC8& aPrefix,
                                                    const TDesC8& aUri) = 0;

        /**
        * Getter for Element's namespace.
        * @since Series60 3.0
        * @return const pointer to the CSenNamespace object of this Element.
        *         Returns NULL, if not set.
        */      
        virtual const CSenNamespace* Namespace() = 0;

        /**
        * @since Series60 3.0
        * @param prefix
        * @return the namespace that is declared for the given prefix
        *         within the scope of this Element. If no such prefix is
        *         declared return NULL.
        */      
        virtual const CSenNamespace* Namespace(const TDesC8& aNsPrefix) = 0;

        /**
        * Get namespace that is declared for the given prefix and namespace 
        * URI within the scope of this element. 
        * @since Series60 3.0
        * @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.
        */
        virtual const CSenNamespace* Namespace( const TDesC8& aNsPrefix,
                                                const TDesC8& aUri) = 0;

        /**
        * @since Series60 3.0
        * @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
        */
        virtual const CSenNamespace* Namespace( const TDesC8& aNsPrefix,
                                                const TBool aCheckInParent) = 0;

        /**
        * Getter for namespace prefix of this element.
        * @since Series60 3.0
        * @return namespace prefix or KNullDesC8 if not set.
        */
        virtual const TDesC8& NsPrefix() const = 0;

        /**
        * Setter for namespace prefix of this element.
        * @since Series60 3.0
        * @param aPrefix:   new namespace prefix for the element.
        */
        virtual void SetPrefixL(const TDesC8& aPrefix) = 0;

        /**
        * Method for checking if the element has any content within.
        * @since Series60 3.0
        * @return ETrue if has content, EFalse if not.
        */
        virtual TBool HasContent() const = 0;

        /**
        * Getter for the content of the element.
        * @since Series60 3.0
        * @return the content or KNullDesC8 if empty.
        */
        virtual TPtrC8 Content() const = 0;

        /**
        * Getter for the content of the element, Unicode (UCS2) version
        * @since Series60 3.0
        * @return content as Unicode. Ownership is transferred to the caller.
        */
        virtual HBufC* ContentUnicodeL() const = 0;
        
        /**
        * Sets the content to the element. Old content is overwritten.
        * @since Series60 3.0
        * @param aContent   The content to be set. Can be KNullDesC8.
        * @return The content of the element or KNullDesC8 if no content was set.
        */
        virtual TPtrC8 SetContentL(const TDesC8& aContent) = 0;

        /**
        * 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.
        * @since Series60 3.0
        * @return reference to the RWriteStream.
        */
        virtual RWriteStream& ContentWriteStreamL() = 0;

        /**
         * Checks if element matches to another element
         * by it's 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.
         */
        virtual TBool ConsistsOfL(MSenElement& aCandidate) = 0;

        /**
        * Get a list of direct children element that have the given
        * name and namespace.
        * @since Series60 3.0
        * @param    aElementArray RPointerArray that will hold matching elements
        * @param    namespaceURI
        * @param    localName
        * @return   KErrNone or some system-wide error code, 
        *           if an error has occurred.
        */
        virtual TInt ElementsL(RPointerArray<CSenElement>& aElementArray,
                                const TDesC8& aNsUri,
                                const TDesC8& aLocalName) = 0;

        /**
        * Get a list of direct children element that have the given
        * name and same namespace as this parent Element.
        * @since Series60 3.0
        * @param    aElementArray RPointerArray that will hold matching elements
        * @param    localName
        * @return   KErrNone or some system-wide error code, 
        *           if an error has occurred.
        */
        virtual TInt ElementsL(RPointerArray<CSenElement>& aElementArray,
                                const TDesC8& aLocalName) = 0;

        /**
        * @since Series60 3.0
        * @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.
        */
        virtual RPointerArray<CSenElement>& ElementsL() = 0;
        
        /**
        * 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.
        * @since Series60 3.0
        * @param aNewNamespace
        * @param aCheckInParent
        * @return the added Namespace, or the equivalent pre-existing one.
        */
        virtual const CSenNamespace* AddNamespaceL(CSenNamespace& aNewNamespace,
                                                    TBool aCheckInParent) = 0;

        /**
        * Gets the value of the given attribute.
        * @since Series60 3.0
        * @param aName: Name of the attribute in question.
        * @return the value of the attribute, or NULL if not found. 
        * Ownership is not transferred to caller.
        */
        virtual const TDesC8* AttrValue(const TDesC8& aName) = 0;

        /**
        * Adds an attribute. If attribute is already existing, 
        *                  the value of the attribute will be replaced.
        * @since Series60 3.0
        * @param aName      Name of the attribute to be added.
        * @param aValue Value of the attribute to be added.
        */
        virtual void AddAttrL(const TDesC8& aName, const TDesC8& aValue) = 0;

        /**
        * Gets all the attributes of this element in an array.
        * @since Series60 3.0
        * @return array of attributes. Array will be empty if element has 
        *         no attributes.
        */
        virtual RPointerArray<CSenBaseAttribute>& AttributesL() = 0;

        /**
        * Gets all the namespaces of this element in an array.
        * @since Series60 3.0
        * @return array of namespaces. Array will be empty if element has 
        *         no namespaces.
        */
        virtual RPointerArray<CSenNamespace>& NamespacesL() = 0;

        /**
        * Gets the parent element of this element.
        * @since Series60 3.0
        * @return the parent element or NULL if no parent set. 
        *           Ownership is NOT transferred to the caller.
        */
        virtual CSenElement* Parent() = 0;

        /**
        * From MSenElement  Sets the parent element to this element. 
        * Notice that the element is not automatically added as a 
        * child of the parent. Parent's AddElementL() must be called 
        * to achieve that.
        *
        * @since Series60 3.0
        * @param apParent:  The wanted parent. Can be NULL.
        * @return   the parent element
        */
        virtual CSenElement* SetParent(CSenElement* apParent) = 0;

        /**
        * Detach the element from its parent.
        * If the element, or one of its children, is dependent
        * on a namespace declared in the scope of the parent
        * copy those namespace declarations to this element.
        * @since Series60 3.0
        * @return this Element. Ownership is NOT transferred to the caller.
        *         or NULL if no parent was set, and nothing was detached.
        */
        virtual CSenElement* DetachL() = 0;

        /**
        * Gets a child element from a specified index.
        * @since Series60 3.0
        * @param  aIndex:   the index what to get
        * @return child element from a current index. NULL if no child in given
        *         index is found
        */
        virtual CSenElement* Child(TInt aIndex) = 0;

        /**
        * Gets the root element. If no parent element, returns this element.
        * @since Series60 3.0
        * @return the root of the tree. Ownership is not transferred.
        */
        virtual MSenElement& Root() = 0;

        /**
        * Gets the child element with the specified local name.
        * Assumes that namespace is the same as this parent element.
        * @since Series60 3.0
        * @param aLocalName is the XML localname of the requested child element
        * @return   the child element or NULL if the child with the specified 
        *           local name is not found. Ownership is NOT transferred.
        */
        virtual CSenElement* Element(const TDesC8& aLocalName) = 0;

        /**
        * Gets the child element with the specified local name and namespace URI.
        * @since Series60 3.0
        * @param aNsUri is the XML namespace of the requested child element
        * @param aLocalName  is the XML localname of the requested child element
        * @return   the child element or NULL if the child with the specified 
        *           criterias is not found. Ownership is NOT transferred.
        */
        virtual CSenElement* Element(const TDesC8& aNsUri,
                                     const TDesC8& aLocalName) = 0;

        /**
        * 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.
        * @since Series60 3.0
        * @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 contain illegal characters.      
        *       KErrSenZeroLengthDescriptor if aLocalName is zero length.
        */
        virtual CSenElement* CreateElementL(const TDesC8& aNsPrefix,
                                            const TDesC8& aLocalName) = 0;

        /**
        * 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.
        * @since Series60 3.0
        * @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
        */
        virtual CSenElement& InsertElementL(CSenElement& aInsertedElement,
                                            const CSenElement& aBeforeElement) = 0;

        /**
        * Adds an Element to the children elements. 
        * Sets this element to be the new parent of the given element.
        * @since Series60 3.0
        * @param aElement:  the element to be added. Ownership is transferred.
        * @return the added Element
        */
        virtual CSenElement& AddElementL(CSenElement& aElement) = 0;

        /**
        * Constructs and adds a new element to the children elements. 
        * Sets this element to be the new parent of the given element.
        * @since Series60 3.0
        * @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.
        */
        virtual CSenElement& AddElementL(   const TDesC8& aNsUri,
                                            const TDesC8& aLocalName) = 0;
        
        /**
        * Constructs and adds a new element to the children elements. 
        * Sets this element to be the new parent of the given element.
        * @since Series60 3.0
        * @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.
        */
        virtual CSenElement& AddElementL(const TDesC8& aNsUri,
                                         const TDesC8& aLocalName,
                                         const TDesC8& aQName) = 0;

        /**
        * 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.
        * @since Series60 3.0
        * @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.
        */
        virtual CSenElement& AddElementL(const TDesC8& aLocalName) = 0;

        /**
        * Remove an element from the childs.
        * @since Series60 3.0
        * @param aElement:  the element to be removed.
        * @return The removed element. May be NULL if nothing was removed
        *           (if child element was not found).
        *           The caller TAKES OWNERSHIP of the removed element.
        */
        virtual CSenElement* RemoveElement(CSenElement& aElement) = 0;

        /**
        * Remove an element from the childs.
        * @since Series60 3.0
        * @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 child element was not found).
        *           The caller TAKES OWNERSHIP of the removed element.
        */
        virtual CSenElement* RemoveElement( const TDesC8& aNsUri,
                                            const TDesC8& aLocalName) = 0;

        /**
        * Remove a child element.
        * @since Series60 3.0
        * @param    aLocalName: the local name of the element to be removed.
        * @return The removed element. May be NULL if nothing was removed
        *           (if child element was not found).
        *
        * The caller takes ownership of the removed element.
        */
        virtual CSenElement* RemoveElement(const TDesC8& aLocalName) = 0;

        /**
        * Replaces a child element with another element.
        * Element's local name and namespace URI will be used to check
        * whether or not that element matches with any existing child.
        * If no matching child element is found this method will add a 
        * new child element.
        *
        * @since Series60 3.0
        * @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.
        */
        virtual CSenElement* ReplaceElementL(CSenElement& aElement) = 0;

        /**
        * Gets the element as an XML buffer. Buffer will 
        * contain all the child elements.
        * @since Series60 3.0
        * @return element as XML. Caller takes ownership.
        */
        virtual HBufC8* AsXmlL() = 0;
        
        /**
        * Gets the element as an unicode (UCS2) XML buffer.
        * Buffer will contain all the child elements.
        * @since Series60 3.0
        * @return element as XML. Caller takes ownership.
        */
        virtual HBufC* AsXmlUnicodeL() = 0;

        /**
        * Element writes itself to a write stream using UTF-8 
        * character-set encoding.
        * @since Series60 3.0
        * @param aWriteStream The stream to write to.
        */
        virtual void WriteAsXMLToL(RWriteStream& aWriteStream) = 0;

        /**
        * Element writes its namespaces to a write stream 
        * using UTF-8 character-set encoding.
        * @since Series60 3.0
        * @param aWriteStream The stream to write to.
        */
        virtual void WriteNamespacesToL(RWriteStream& aWriteStream) = 0;

        /**
        * Offers the M-class interface pointer to this XML 
        * element.
        * @since Series60 3.0
        * @return the current object as element. Ownership is NOT transferred.
        */
        virtual MSenElement* AsElement() = 0;

        /**
        * Copies content from given element to this element appending to the 
        * existing content if there is any.
        * @since Series60 3.0
        * @param aSource The source element.
        */
        virtual void CopyFromL(CSenElement& aSource) = 0;

        /**
        * (Re-) Set the name and namespace of this Element. The element will be
        * given the localName in the the given namespace. A prefix will be
        * computed from the qualified name.
        * This method should be used with care and is mainly intended for
        * protected use in implementations.
        * @since Series60 3.0
        * @param aNamespaceURI The new namespace URI.
        * @param aLocalName The new local name.
        * @param aQName The new qualified name.
        */
        virtual void Set(const TDesC8& aNamespaceURI, const TDesC8& aLocalName, const TDesC8& aQName) = 0;

        /**
        * Adds new attributes to the element.
        * @since Series60 3.0
        * @param aAttrs:    the array of attributes.
        */
        virtual void AddAttributesL(const RAttributeArray& apAttrs) = 0;
    };

#endif //SEN_ELEMENT_H

// End of File

