/*
* 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 "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: 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