--- a/epoc32/include/xml/dom/xmlengattr.h Wed Mar 31 12:27:01 2010 +0100
+++ b/epoc32/include/xml/dom/xmlengattr.h Wed Mar 31 12:33:34 2010 +0100
@@ -1,192 +1,166 @@
-/*
-* 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
-*
-*/
-
-
-
-
+// Copyright (c) 2006-2009 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:
+// Attribute node functions
+//
-#ifndef XMLENGINE_ATTR_H_INCLUDED
-#define XMLENGINE_ATTR_H_INCLUDED
+/**
+ @file
+ @publishedAll
+ @released
+*/
+#ifndef XMLENGATTR_H
+#define XMLENGATTR_H
-#include "xmlengnode.h"
+#include <xml/dom/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
- */
+This class represents a XML attribute in the DOM tree.
+*/
class TXmlEngAttr : public TXmlEngNode
{
public:
- /**
- * Default constructor
- *
- * @since S60 v3.1
- */
+ /** Default constructor */
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)
- */
+ Clones attribute node.
+
+ Note: Resets the namespace of the attribute. To avoid this, use
+ TXmlEngNode::CopyToL(), which finds an appropriate or creates
+ a new namespace declaration on the new parent node (argument should be
+ an TXmlEngElement handle)
+
+ @see TXmlEngNode::CopyToL()
+
+ @return A copy of this attribute
+ @leave - One of the system-wide error codes
+ */
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.
- */
+ Get the owner element.
+
+ 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.
+
+ If there is no owning element, a NULL element is returned.
+
+ @return TXmlEngElement that contains the attribute
+ */
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()
- */
+ Get the attribute name. Equal to TXmlEngNode::Name(), but works faster.
+
+ @return Local name of the attribute
+ @pre Node must not be NULL
+ @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()
- */
+ Get the attribute's value. If the value consists of more than one TXmlEngTextNode,
+ as children of the attribute, only the beginning of the value is returned. This
+ happens when the value is represented by list of TXmlEngTextNode and
+ TXmlEngEntityReference nodes.
+
+ @return The attribute's value
+ @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.
- */
+ Get a copy of attribute content. Since the value may be composed from a set of
+ TXmlEngTextNode and TXmlEngEntityReference nodes, the returned result is a newly allocated
+ RBuf, which should be closed by the caller.
+
+ Example usage of the API:
+ @code
+ RBuf8 value;
+ attr.WholeValueCopyL(value);
+ ...
+ value.Close();
+ @endcode
+
+ In most cases using Value() is enough (and it needs no memory allocation).
+ Use IsSimpleTextContents() if there are doubts whether Value() can be used safely.
+
+ @return Complex value of the attribute, probably consisting of text nodes and entity references
+ @leave KXmlEngErrNullNode Node is NULL
+ @leave - One of the system-wide error codes
+ @see TXmlEngAttr::Value()
+ @see TXmlEngNode::Value()
+ @see TXmlEngNode::IsSimpleTextContents()
+ @see TXmlEngNode::WholeTextContentsCopyL()
+ */
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&)
- */
+ Sets the value of the attribute. The new value should not contain entity
+ references. Entity references are not expanded, but used as text, thus
+ the string "abc & def" is copied directly as "abc & def" without
+ expansion.
+
+ @param aNewValue A string value for the attribute
+ @leave KXmlEngErrNullNode Node is NULL
+ @leave - One of the system-wide error codes
+ @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&)
- */
+ Sets the value of the attribute from escaped XML character data that may contain
+ entity references.
+
+ If the value contains entity references, then the resulting
+ content of the attribute is a list of TXmlEngTextNode
+ and TXmlEngEntityReference nodes.
+ Predefined entities are converted into characters they represent.
+
+ @param aNewValue is a new attribute value
+ @leave KXmlEngErrNullNode Node is NULL
+ @leave - One of the system-wide error codes
+ @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&)
- */
+ Sets new attribute value exactly as presented in the string.
+ Predefined entities are not converted into characters they represent.
+
+ @param aNewValue is the new attribute value
+ @leave KXmlEngErrNullNode Node is NULL
+ @leave - One of the system-wide error codes
+ @see TXmlEngAttr::SetValueL(const TDesC8&)
+ */
IMPORT_C void SetValueNoEncL(const TDesC8& aNewValue );
protected:
/**
- * Constructor
- *
- * @since S60 v3.1
- * @param aInternal attribute pointer
- */
+ Constructor
+ @param aInternal attribute pointer
+ */
inline TXmlEngAttr(void* aInternal);
};
-#include "xmlengattr.inl"
+#include <xml/dom/xmlengattr.inl>
-#endif /* XMLENGINE_ATTR_H_INCLUDED */
+#endif /* XMLENGATTR_H */
+