/*

 * Copyright (c) 2004-2006 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:       Attribute node functions

 *

 */

 #ifndef XMLENGINE_ATTR_H_INCLUDED

 #define XMLENGINE_ATTR_H_INCLUDED

 #include "xmlengnode.h"

 /**

  * Instance of TXmlEngAttr class represents an XML attribute in the DOM tree.

  * 

  * Is a storage attributes properties. Implements DOM action for it.

  * 

  * @lib XmlEngineDOM.lib

  * @since S60 v3.1

  */

 class TXmlEngAttr : public TXmlEngNode

 {

   public:

     /**

      * Default constructor

      *

      * @since S60 v3.1

      */

     inline TXmlEngAttr();

     /**

      * Clones attribute node

      *

      * @since S60 v3.1

      * @return A copy of the attribute with its value

      *

      * @note Namespace of the attribute is reset; use 

      * TXmlEngNode::CopyToL(TXmlEngNode), which finds appropriate or creates

      * new namespace declaration on the new parent node (argument should be

      * an TXmlEngElement handle)

      *

      * @see CopyToL(TXmlEngNode)

      */

     IMPORT_C TXmlEngAttr CopyL() const;

     /**

      * Get owner element

      *

      * @since S60 v3.1

      * @return TXmlEngElement that contains the attribute

      *

      * Same as TXmlEngNode::ParentNode() but returns TXmlEngElement 

      * instead of TXmlEngNode.

      *

      * @note Copies of attributes [TXmlEngAttr::CopyL()] and newly created 

      * attribute nodes [RXmlEngDocument::CreateAttributeL(..)] do not have 

      * parent element until they are attached to some element.

      */

     IMPORT_C const TXmlEngElement OwnerElement() const;

     /**

      * Check attribute name.

      *

      * @since S60 v3.1

      * @return Local name of the attribute

      *

      * @note Equal to TXmlEngNode::Name(), but works faster.

      *

      * Never call this on NULL object!

      * @see TXmlEngNode::Name()

      */

     IMPORT_C TPtrC8 Name() const;

     /**

      * Get element value.

      *

      * @since S60 v3.1

      * @return Attribute's contents

      *

      * @note For values consisting of more then one TXmlEngTextNode node 

      * (as attribute's child) returns only the begining of the value; 

      * this happens when the value is represented by list of TXmlEngTextNode

      * and TXmlEngEntityReference nodes.

      * 

      * @see IsSimpleContents(), WholeValueCopyL()

      */

     IMPORT_C TPtrC8 Value() const; 

     /**

      * Get copy of attribute content

      *

      * @since S60 v3.1

      * @return Complex value of the attribute,

      *     probably consisting of text nodes and entity references

      *

      * Since the value may be composed from a set of TXmlEngTextNode

      * and EntityRefernce nodes, the returned result is newly allocated 

      * string, which should be freed by caller.

      * 

      * <B style="color: red">BE SURE TO FREE THE RESULT STRING!!!</B>

      *

      * Example usage of the API:

      * @code

      *    RBuf8 value;

 	 *    attr.WholeValueCopyL(value);

      *    ...

      *    value.Close();

      * @endcode

      *

      * @see TXmlEngAttr::Value(), TXmlEngNode::Value(),

      * TXmlEngNode::IsSimpleTextContents(), 

      * TXmlEngNode::WholeTextContentsCopyL()

      *

      * @note In most cases using Value() is enough (and it needs no memory allocation).

      *     Use IsSimpleTextContents() if there doubts can Value() be used or not safely.

      */

     IMPORT_C void WholeValueCopyL(RBuf8& aBuffer) const;

     /**

      * Sets new value of the attribute. Provided new value will be escaped 

      * as needed.

      *

 	 * @ since S60 v3.1

      * @param aNewValue A string value for the attribute

      *

      * The new value should not contain entity references. 

      * Entity references are not expanded, but used as text, because 

      * the ampersand (&) character of reference is escaped.

      *

      * @see SetEscapedValueL(const TDesC8&)

      */

     IMPORT_C void SetValueL(const TDesC8& aNewValue);

     /**

      * Sets new value from escaped XML character data that may contain 

      * entity references.

      *

      * The value as if it is an escaped contents from XML file.

      * If the value contains entity references, then the resulting

      * content of the attribute is a list of TXmlEngTextNode 

      * and TXmlEngEntityRefeerence nodes.

      * Predefined entities are converted into characters they represent.

      * 

      * @param aNewValue is a new attribute value

      * @since S60 v3.1

      *

      * @see TXmlEngAttr::SetValueL(const TDesC8&)

      */

     IMPORT_C void SetEscapedValueL(const TDesC8& aNewValue);

 	/**

 	 * Sets new attribute value exactly as presented in the string.

 	 *

 	 * Predefined entities are not converted into characters they represent.

 	 *

      * @param aNewValue is a new attribute value 

      * @since S60 v3.2

      *

      * @see TXmlEngAttr::SetValueL(const TDesC8&)

      */

 	IMPORT_C void SetValueNoEncL(const TDesC8& aNewValue );

 protected:

     /**

      * Constructor

      *

      * @since S60 v3.1

      * @param aInternal attribute pointer

      */

     inline TXmlEngAttr(void* aInternal);

 };

 #include "xmlengattr.inl"

 #endif /* XMLENGINE_ATTR_H_INCLUDED */