1.1 --- a/epoc32/include/xml/dom/xmlengattr.h Wed Mar 31 12:27:01 2010 +0100
1.2 +++ b/epoc32/include/xml/dom/xmlengattr.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -1,192 +1,166 @@
1.4 -/*
1.5 -* Copyright (c) 2004-2006 Nokia Corporation and/or its subsidiary(-ies).
1.6 -* All rights reserved.
1.7 -* This component and the accompanying materials are made available
1.8 -* 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
1.9 -* which accompanies this distribution, and is available
1.10 -* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 -*
1.12 -* Initial Contributors:
1.13 -* Nokia Corporation - initial contribution.
1.14 -*
1.15 -* Contributors:
1.16 -*
1.17 -* Description: Attribute node functions
1.18 -*
1.19 -*/
1.20 +// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
1.21 +// All rights reserved.
1.22 +// This component and the accompanying materials are made available
1.23 +// under the terms of "Eclipse Public License v1.0"
1.24 +// which accompanies this distribution, and is available
1.25 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.26 +//
1.27 +// Initial Contributors:
1.28 +// Nokia Corporation - initial contribution.
1.29 +//
1.30 +// Contributors:
1.31 +//
1.32 +// Description:
1.33 +// Attribute node functions
1.34 +//
1.35
1.36
1.37
1.38 -
1.39 -
1.40 -
1.41 -
1.42 -#ifndef XMLENGINE_ATTR_H_INCLUDED
1.43 -#define XMLENGINE_ATTR_H_INCLUDED
1.44 -
1.45 -#include "xmlengnode.h"
1.46 -
1.47 /**
1.48 - * Instance of TXmlEngAttr class represents an XML attribute in the DOM tree.
1.49 - *
1.50 - * Is a storage attributes properties. Implements DOM action for it.
1.51 - *
1.52 - * @lib XmlEngineDOM.lib
1.53 - * @since S60 v3.1
1.54 - */
1.55 + @file
1.56 + @publishedAll
1.57 + @released
1.58 +*/
1.59 +#ifndef XMLENGATTR_H
1.60 +#define XMLENGATTR_H
1.61 +
1.62 +#include <xml/dom/xmlengnode.h>
1.63 +
1.64 +/**
1.65 +This class represents a XML attribute in the DOM tree.
1.66 +*/
1.67 class TXmlEngAttr : public TXmlEngNode
1.68 {
1.69 public:
1.70 - /**
1.71 - * Default constructor
1.72 - *
1.73 - * @since S60 v3.1
1.74 - */
1.75 + /** Default constructor */
1.76 inline TXmlEngAttr();
1.77
1.78 + /**
1.79 + Clones attribute node.
1.80
1.81 - /**
1.82 - * Clones attribute node
1.83 - *
1.84 - * @since S60 v3.1
1.85 - * @return A copy of the attribute with its value
1.86 - *
1.87 - * @note Namespace of the attribute is reset; use
1.88 - * TXmlEngNode::CopyToL(TXmlEngNode), which finds appropriate or creates
1.89 - * new namespace declaration on the new parent node (argument should be
1.90 - * an TXmlEngElement handle)
1.91 - *
1.92 - * @see CopyToL(TXmlEngNode)
1.93 - */
1.94 + Note: Resets the namespace of the attribute. To avoid this, use
1.95 + TXmlEngNode::CopyToL(), which finds an appropriate or creates
1.96 + a new namespace declaration on the new parent node (argument should be
1.97 + an TXmlEngElement handle)
1.98 +
1.99 + @see TXmlEngNode::CopyToL()
1.100 +
1.101 + @return A copy of this attribute
1.102 + @leave - One of the system-wide error codes
1.103 + */
1.104 IMPORT_C TXmlEngAttr CopyL() const;
1.105
1.106 /**
1.107 - * Get owner element
1.108 - *
1.109 - * @since S60 v3.1
1.110 - * @return TXmlEngElement that contains the attribute
1.111 - *
1.112 - * Same as TXmlEngNode::ParentNode() but returns TXmlEngElement
1.113 - * instead of TXmlEngNode.
1.114 - *
1.115 - * @note Copies of attributes [TXmlEngAttr::CopyL()] and newly created
1.116 - * attribute nodes [RXmlEngDocument::CreateAttributeL(..)] do not have
1.117 - * parent element until they are attached to some element.
1.118 - */
1.119 + Get the owner element.
1.120 +
1.121 + Same as TXmlEngNode::ParentNode() but returns TXmlEngElement
1.122 + instead of TXmlEngNode.
1.123 +
1.124 + Note: Copies of attributes [TXmlEngAttr::CopyL()] and newly created
1.125 + attribute nodes [RXmlEngDocument::CreateAttributeL()] do not have
1.126 + parent element until they are attached to some element.
1.127 +
1.128 + If there is no owning element, a NULL element is returned.
1.129 +
1.130 + @return TXmlEngElement that contains the attribute
1.131 + */
1.132 IMPORT_C const TXmlEngElement OwnerElement() const;
1.133
1.134 /**
1.135 - * Check attribute name.
1.136 - *
1.137 - * @since S60 v3.1
1.138 - * @return Local name of the attribute
1.139 - *
1.140 - * @note Equal to TXmlEngNode::Name(), but works faster.
1.141 - *
1.142 - * Never call this on NULL object!
1.143 - * @see TXmlEngNode::Name()
1.144 - */
1.145 + Get the attribute name. Equal to TXmlEngNode::Name(), but works faster.
1.146 +
1.147 + @return Local name of the attribute
1.148 + @pre Node must not be NULL
1.149 + @see TXmlEngNode::Name()
1.150 + */
1.151 IMPORT_C TPtrC8 Name() const;
1.152
1.153 /**
1.154 - * Get element value.
1.155 - *
1.156 - * @since S60 v3.1
1.157 - * @return Attribute's contents
1.158 - *
1.159 - * @note For values consisting of more then one TXmlEngTextNode node
1.160 - * (as attribute's child) returns only the begining of the value;
1.161 - * this happens when the value is represented by list of TXmlEngTextNode
1.162 - * and TXmlEngEntityReference nodes.
1.163 - *
1.164 - * @see IsSimpleContents(), WholeValueCopyL()
1.165 - */
1.166 + Get the attribute's value. If the value consists of more than one TXmlEngTextNode,
1.167 + as children of the attribute, only the beginning of the value is returned. This
1.168 + happens when the value is represented by list of TXmlEngTextNode and
1.169 + TXmlEngEntityReference nodes.
1.170 +
1.171 + @return The attribute's value
1.172 + @see IsSimpleContents(), WholeValueCopyL()
1.173 + */
1.174 IMPORT_C TPtrC8 Value() const;
1.175
1.176 /**
1.177 - * Get copy of attribute content
1.178 - *
1.179 - * @since S60 v3.1
1.180 - * @return Complex value of the attribute,
1.181 - * probably consisting of text nodes and entity references
1.182 - *
1.183 - * Since the value may be composed from a set of TXmlEngTextNode
1.184 - * and EntityRefernce nodes, the returned result is newly allocated
1.185 - * string, which should be freed by caller.
1.186 - *
1.187 - * <B style="color: red">BE SURE TO FREE THE RESULT STRING!!!</B>
1.188 - *
1.189 - * Example usage of the API:
1.190 - * @code
1.191 - * RBuf8 value;
1.192 - * attr.WholeValueCopyL(value);
1.193 - * ...
1.194 - * value.Close();
1.195 - * @endcode
1.196 - *
1.197 - * @see TXmlEngAttr::Value(), TXmlEngNode::Value(),
1.198 - * TXmlEngNode::IsSimpleTextContents(),
1.199 - * TXmlEngNode::WholeTextContentsCopyL()
1.200 - *
1.201 - * @note In most cases using Value() is enough (and it needs no memory allocation).
1.202 - * Use IsSimpleTextContents() if there doubts can Value() be used or not safely.
1.203 - */
1.204 + Get a copy of attribute content. Since the value may be composed from a set of
1.205 + TXmlEngTextNode and TXmlEngEntityReference nodes, the returned result is a newly allocated
1.206 + RBuf, which should be closed by the caller.
1.207 +
1.208 + Example usage of the API:
1.209 + @code
1.210 + RBuf8 value;
1.211 + attr.WholeValueCopyL(value);
1.212 + ...
1.213 + value.Close();
1.214 + @endcode
1.215 +
1.216 + In most cases using Value() is enough (and it needs no memory allocation).
1.217 + Use IsSimpleTextContents() if there are doubts whether Value() can be used safely.
1.218 +
1.219 + @return Complex value of the attribute, probably consisting of text nodes and entity references
1.220 + @leave KXmlEngErrNullNode Node is NULL
1.221 + @leave - One of the system-wide error codes
1.222 + @see TXmlEngAttr::Value()
1.223 + @see TXmlEngNode::Value()
1.224 + @see TXmlEngNode::IsSimpleTextContents()
1.225 + @see TXmlEngNode::WholeTextContentsCopyL()
1.226 + */
1.227 IMPORT_C void WholeValueCopyL(RBuf8& aBuffer) const;
1.228
1.229 /**
1.230 - * Sets new value of the attribute. Provided new value will be escaped
1.231 - * as needed.
1.232 - *
1.233 - * @ since S60 v3.1
1.234 - * @param aNewValue A string value for the attribute
1.235 - *
1.236 - * The new value should not contain entity references.
1.237 - * Entity references are not expanded, but used as text, because
1.238 - * the ampersand (&) character of reference is escaped.
1.239 - *
1.240 - * @see SetEscapedValueL(const TDesC8&)
1.241 - */
1.242 + Sets the value of the attribute. The new value should not contain entity
1.243 + references. Entity references are not expanded, but used as text, thus
1.244 + the string "abc & def" is copied directly as "abc & def" without
1.245 + expansion.
1.246 +
1.247 + @param aNewValue A string value for the attribute
1.248 + @leave KXmlEngErrNullNode Node is NULL
1.249 + @leave - One of the system-wide error codes
1.250 + @see SetEscapedValueL(const TDesC8&)
1.251 + */
1.252 IMPORT_C void SetValueL(const TDesC8& aNewValue);
1.253
1.254 /**
1.255 - * Sets new value from escaped XML character data that may contain
1.256 - * entity references.
1.257 - *
1.258 - * The value as if it is an escaped contents from XML file.
1.259 - * If the value contains entity references, then the resulting
1.260 - * content of the attribute is a list of TXmlEngTextNode
1.261 - * and TXmlEngEntityRefeerence nodes.
1.262 - * Predefined entities are converted into characters they represent.
1.263 - *
1.264 - * @param aNewValue is a new attribute value
1.265 - * @since S60 v3.1
1.266 - *
1.267 - * @see TXmlEngAttr::SetValueL(const TDesC8&)
1.268 - */
1.269 + Sets the value of the attribute from escaped XML character data that may contain
1.270 + entity references.
1.271 +
1.272 + If the value contains entity references, then the resulting
1.273 + content of the attribute is a list of TXmlEngTextNode
1.274 + and TXmlEngEntityReference nodes.
1.275 + Predefined entities are converted into characters they represent.
1.276 +
1.277 + @param aNewValue is a new attribute value
1.278 + @leave KXmlEngErrNullNode Node is NULL
1.279 + @leave - One of the system-wide error codes
1.280 + @see TXmlEngAttr::SetValueL(const TDesC8&)
1.281 + */
1.282 IMPORT_C void SetEscapedValueL(const TDesC8& aNewValue);
1.283
1.284 /**
1.285 - * Sets new attribute value exactly as presented in the string.
1.286 - *
1.287 - * Predefined entities are not converted into characters they represent.
1.288 - *
1.289 - * @param aNewValue is a new attribute value
1.290 - * @since S60 v3.2
1.291 - *
1.292 - * @see TXmlEngAttr::SetValueL(const TDesC8&)
1.293 - */
1.294 + Sets new attribute value exactly as presented in the string.
1.295 + Predefined entities are not converted into characters they represent.
1.296 +
1.297 + @param aNewValue is the new attribute value
1.298 + @leave KXmlEngErrNullNode Node is NULL
1.299 + @leave - One of the system-wide error codes
1.300 + @see TXmlEngAttr::SetValueL(const TDesC8&)
1.301 + */
1.302 IMPORT_C void SetValueNoEncL(const TDesC8& aNewValue );
1.303
1.304 protected:
1.305 /**
1.306 - * Constructor
1.307 - *
1.308 - * @since S60 v3.1
1.309 - * @param aInternal attribute pointer
1.310 - */
1.311 + Constructor
1.312 + @param aInternal attribute pointer
1.313 + */
1.314 inline TXmlEngAttr(void* aInternal);
1.315 };
1.316
1.317 -#include "xmlengattr.inl"
1.318 +#include <xml/dom/xmlengattr.inl>
1.319
1.320 -#endif /* XMLENGINE_ATTR_H_INCLUDED */
1.321 +#endif /* XMLENGATTR_H */
1.322 +