/*

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