diff -r 000000000000 -r 62f9d29f7211 websrv_pub/xml_extensions_api/inc/SenElement.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/websrv_pub/xml_extensions_api/inc/SenElement.h Thu Jan 07 16:19:19 2010 +0200 @@ -0,0 +1,559 @@ +/* +* 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 +#include +#include +#include + +#include + +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& 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& 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& 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& 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& 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 +