/*
* Copyright (c) 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: SIMPLE data element
*
*/
#ifndef M_simpleelement_H
#define M_simpleelement_H
#include <e32std.h>
#include <msimpleattribute.h>
// FORWARD DECLARATION
class MSimpleNamespace;
/**
* MSimpleDocument
*
* SIMPLE data document
*
* @lib simplexmlutils
* @since S60 3.2
*/
class MSimpleElement
{
public:
/**
* Destroy this element entity and all its descendant elements.
* @since S60 3.2
*/
virtual void Close() = 0;
/**
* Getter for Element's local name.
* LocalName and Namespace are given in factory method.
* @since S60 3.2
* @return KNullDesC8 if not set
*/
virtual const TDesC8& LocalName() = 0;
/**
* Getter for Element's own default namespace.
*
* @since S60 3.2
* @return pointer to the MSimpleNamespace object of this Element.
* NULL if not set for this element. Ownership is transferred.
*/
virtual MSimpleNamespace* DefNamespaceL() = 0;
/**
* Method for checking if the element has any content within.
*
* @since S60 3.2
* @return ETrue if has content, EFalse if not.
*/
virtual TBool HasContent() = 0;
/**
* Getter for the content of the element, unicode version.
*
* @since S60 3.2
* @return content as unicode. Ownership IS TRANSFERRED to the caller.
*/
virtual HBufC* ContentUnicodeL()= 0;
/**
* Sets the content to the element. Old content is overwritten.
*
* @since S60 3.2
* @param aContent: The content to be set. Can be KNullDesC
*/
virtual void SetContentUnicodeL( const TDesC& aContent ) = 0;
/**
* Getting the child elements of this element.
* @param aElementArray: Array to be filled with the child elements,
* or empty array if no childs.
* Any modifications made on the returned items
* modify the real childs.
* Do NOT call ResetAndDestroy() for the array,
* you may call Reset() only. The array is valid only till
* the next call of this method in this entity. New elements are
* not attached to the array automatically, so that you have
* to re-call this method if you wish to see all the elements
* after calling AddSimpleElementL() method.
* @return KErrNone ok
* KErrNotFound No child elements exist.
*/
virtual TInt SimpleElementsL( RPointerArray<MSimpleElement>& aElementArray ) = 0;
/**
* Gets the value of the given attribute.
*
* @since S60 3.2
* @param aName: Name of the attribute in question.
* @return the value of the attribute, or NULL if not found. Ownership is
* TRANSFERRED.
*/
virtual HBufC* AttrValueLC( const TDesC8& aName ) = 0;
/**
* 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.
*/
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 S60 3.2
* @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 TDesC& aValue ) = 0;
/**
* From MSimpleElement
* Gets all the attributes of this element in an array.
*
* @since S60 3.2
* @param aArray: Array to be filled with the attributes,
* or empty array if no childs.
* Any modifications made on the returned items
* modify the real attributes.
* Do NOT call ResetAndDestroy() for the array,
* you may call Reset() only. The array is valid only till
* the next call of this method in this entity. New attributes are
* not attached to the array automatically, so that you have
* to re-call this method if you wish to see all the elements
* after calling AddAttrL() method.
* @return KErrNone ok
* KErrNotFound No child elements exist.
*/
virtual TInt SimpleAttributesL( RPointerArray<MSimpleAttribute>& aArray ) = 0;
/**
* Gets the parent element of this element.
*
* @since S60 3.2
* @return the parent element or NULL if no parent set.
* Ownership is NOT transferred to the caller.
*/
virtual MSimpleElement* SimpleParentL() = 0;
/**
* Detach the element from its parent.
* Notice that the current element instance should not be
* used after this method is called successfully.
* Leaves with KErrNotFound if parent was not set and
* nothing to detach.
*
* @since S60 3.2
*/
virtual void DetachSimpleL() = 0;
/**
* Constructs and adds a new element to the children elements.
* Sets this element to be the new parent of the given element.
*
* @since S60 3.2
* @param aNsUri: namespace URI of the new element
* @param aLocalName: local name of the new element
* @return the added Element.
* OWNERSHIP IS TRANSFERRED.
* Leave if aLocalName contains illegal characters or
* if aLocalName is zero length.
*/
virtual MSimpleElement* AddSimpleElementL(
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.
* 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 S60 3.2
* @param aLocalName: local name of the new element
* @return the added Element. OWNERSHIP IS TRANSFERRED.
* Leave if aLocalName contains illegal characters.
*/
virtual MSimpleElement* AddSimpleElementL(
const TDesC8& aLocalName ) = 0;
/**
* Remove an element from the childs.
*
* @since S60 3.2
* @param aNsUri: the namespace URI of the element to be removed.
* @param aLocalName: the local name of the element to be removed.
*/
virtual void RemoveSimpleElement(
const TDesC8& aNsUri,
const TDesC8& aLocalName ) = 0;
};
#endif
// End of File