diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/xml/dom/xmlengattr.h --- 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 - -#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 - */ + @file + @publishedAll + @released +*/ +#ifndef XMLENGATTR_H +#define XMLENGATTR_H + +#include + +/** +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. - /** - * 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) - */ + 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. - * - * BE SURE TO FREE THE RESULT STRING!!! - * - * 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 -#endif /* XMLENGINE_ATTR_H_INCLUDED */ +#endif /* XMLENGATTR_H */ +