1.1 --- a/epoc32/include/xml/dom/xmlengdocument.h Wed Mar 31 12:27:01 2010 +0100
1.2 +++ b/epoc32/include/xml/dom/xmlengdocument.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -1,478 +1,516 @@
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: Document node functions
1.18 -*
1.19 +// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
1.20 +// All rights reserved.
1.21 +// This component and the accompanying materials are made available
1.22 +// under the terms of "Eclipse Public License v1.0"
1.23 +// which accompanies this distribution, and is available
1.24 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.25 +//
1.26 +// Initial Contributors:
1.27 +// Nokia Corporation - initial contribution.
1.28 +//
1.29 +// Contributors:
1.30 +//
1.31 +// Description:
1.32 +// Document node functions
1.33 +//
1.34 +
1.35 +
1.36 +
1.37 +/**
1.38 + @file
1.39 + @publishedAll
1.40 + @released
1.41 */
1.42 -
1.43 -
1.44 -
1.45 -
1.46 -
1.47 -
1.48 -#ifndef XMLENGINE_DOCUMENT_H_INCLUDED
1.49 -#define XMLENGINE_DOCUMENT_H_INCLUDED
1.50 +#ifndef XMLENGDOCUMENT_H
1.51 +#define XMLENGDOCUMENT_H
1.52
1.53 #include <f32file.h>
1.54
1.55 -#include "xmlengnode.h"
1.56 -#include "xmlengserializationoptions.h"
1.57 +#include <xml/dom/xmlengnode.h>
1.58 +#include <xml/dom/xmlengserializationoptions.h>
1.59
1.60 -// FORWARD DECLARATION
1.61 class RXmlEngDOMImplementation;
1.62
1.63 /**
1.64 - * Instance of RXmlEngDocument class represents an XML document in the DOM tree.
1.65 - *
1.66 - * Is a storage all nodes and information about XML data.
1.67 - *
1.68 - * @lib XmlEngineDOM.lib
1.69 - * @since S60 v3.1
1.70 - */
1.71 +This class represents an XML document in the DOM tree. It stores all nodes
1.72 +and associated information about the XML document.
1.73 +
1.74 +This class implements the interface. Another class, RXmlEngDOMImplementation,
1.75 +provides the implementation. An instance of RXmlEngDOMImplementation must be
1.76 +constructed and opened first and passed to RXmlEngDocument::OpenL().
1.77 +*/
1.78 class RXmlEngDocument : public TXmlEngNode
1.79 {
1.80 public:
1.81 - /**
1.82 - * Default constructor.
1.83 - *
1.84 - * Instance of RXmlEngDocument must be "opened" with one of OpenL() overloads.
1.85 - *
1.86 - * @since S60 v3.1
1.87 - */
1.88 + /**
1.89 + Default constructor. An instance of RXmlEngDocument must be "opened" with
1.90 + one of OpenL() overloads before methods are invoked on the object.
1.91 + */
1.92 IMPORT_C RXmlEngDocument();
1.93
1.94 /**
1.95 - * Opens the document.
1.96 - *
1.97 - * @since S60 v3.2
1.98 - * @param aDOMImpl DOM implementation object
1.99 - * @return KErrNone if succeed.
1.100 - */
1.101 + Opens the document.
1.102 + @param aDOMImpl An opened DOM implementation object
1.103 + @leave - One of the system-wide error codes
1.104 + */
1.105 IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl);
1.106
1.107 /**
1.108 - * Opens the document.
1.109 - *
1.110 - * @since S60 v3.2
1.111 - * @param aDOMImpl DOM implementation object
1.112 - * @param aInternal Document pointer
1.113 - * @return KErrNone if succeed.
1.114 - */
1.115 + Opens the document, initializing it with the internal state pointer from
1.116 + another RXmlEngDocument. This document becomes an alias for the document
1.117 + whose state is represented by aInternal and a change in either document
1.118 + will be reflected in the other. Close() need only be called once, however,
1.119 + it is not an error to call Close() on each RXmlEngDocument.
1.120 +
1.121 + @param aDOMImpl An opened DOM implementation object
1.122 + @param aInternal The internal document state to initialize this object with
1.123 + @leave - One of the system-wide error codes
1.124 + */
1.125 IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl, void* aInternal);
1.126
1.127 - /**
1.128 - * Opens the document.
1.129 - *
1.130 - * @since S60 v3.2
1.131 - * @param aDOMImpl DOM implementation object
1.132 - * @param aRoot element taht will be root of the DOM tree
1.133 - * @return KErrNone if succeed.
1.134 - */
1.135 + /**
1.136 + Opens the document and adds aRoot as the root of the DOM tree. If aRoot is
1.137 + currently part of another document, it will be unlinked. Ownership is
1.138 + transferred to this document.
1.139 +
1.140 + @param aDOMImpl An opened DOM implementation object
1.141 + @param aRoot The element that will be the root of the DOM tree
1.142 + @leave - One of the system-wide error codes
1.143 + */
1.144 IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl, TXmlEngElement aRoot);
1.145
1.146 - /**
1.147 - * Closes document
1.148 - *
1.149 - * @since S60 v3.1
1.150 - */
1.151 + /**
1.152 + Closes document: All owned nodes, child nodes, and namespaces are freed. All
1.153 + data containers on the data container list are freed.
1.154 + */
1.155 IMPORT_C void Close();
1.156
1.157 - /**
1.158 - * Serializes document tree into a file. For nodes containing binary data in the form of BinaryDataContainer,
1.159 - * FileContainer or ChunkContainer, client can implement custom serialization by implementing the interface
1.160 - * MXmlEngDataSerializer and specify the pointer in iDataSerializer member of aSaveOptions parameter. If no
1.161 - * custom serialization is specified, the binary data container nodes are serialized like text nodes.
1.162 - *
1.163 - * @since S60 v3.2
1.164 - * @param aFileName A file name (with path)
1.165 - * @param aRoot Root node to be serialized
1.166 - * @param aSaveOptions Options that control how serialization is performed
1.167 - * @return Number of byte written
1.168 - * @leave KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding, KErrDiskFull.
1.169 - */
1.170 + /**
1.171 + Serializes document tree into a file. For nodes containing binary data in
1.172 + the form of BinaryDataContainer, FileContainer or ChunkContainer, the
1.173 + client can implement custom serialization by implementing the
1.174 + MXmlEngDataSerializer interface and saving a pointer to the customer
1.175 + serializer in the iDataSerializer member of the aSaveOptions parameter. If
1.176 + no custom serialization is specified, the binary data container nodes are
1.177 + serialized like text nodes.
1.178 +
1.179 + If no aRoot is provided, the entire DOM tree is serialized. aRoot does not
1.180 + need to be owned by this document.
1.181 +
1.182 + @param aFileName A file name (with path)
1.183 + @param aRoot Root node to be serialized
1.184 + @param aSaveOptions Options that control how serialization is performed
1.185 + @return Number of bytes written
1.186 + @leave KXmlEngErrWrongEncoding Encoding not understood
1.187 + @leave KXmlEngErrWrongUseOfAPI Document is NULL
1.188 + @leave KXmlEngErrNegativeOutputSize The data to be serialized has a negative size
1.189 + @leave - One of the system-wide error codes
1.190 + */
1.191 IMPORT_C TInt SaveL( const TDesC& aFileName,
1.192 TXmlEngNode aRoot = TXmlEngNode(),
1.193 const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions() ) const;
1.194
1.195 /**
1.196 - * Serializes document tree into a file. For nodes containing binary data in the form of BinaryDataContainer,
1.197 - * FileContainer or ChunkContainer, client can implement custom serialization by implementing the interface
1.198 - * MXmlEngDataSerializer and specify the pointer in iDataSerializer member of aSaveOptions parameter. If no
1.199 - * custom serialization is specified, the binary data container nodes are serialized like text nodes.
1.200 - *
1.201 - * @since S60 v3.2
1.202 - * @param aRFs File Server session
1.203 - * @param aFileName A file name (with path)
1.204 - * @param aRoot Root node to be serialized
1.205 - * @param aSaveOptions Options that control how serialization is performed
1.206 - * @return Number of byte written
1.207 - * @leave KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding, KErrDiskFull.
1.208 - */
1.209 + Serializes document tree into a file. For nodes containing binary data in
1.210 + the form of BinaryDataContainer, FileContainer or ChunkContainer, the
1.211 + client can implement custom serialization by implementing the
1.212 + MXmlEngDataSerializer interface and saving a pointer to the customer
1.213 + serializer in the iDataSerializer member of the aSaveOptions parameter. If
1.214 + no custom serialization is specified, the binary data container nodes are
1.215 + serialized like text nodes.
1.216 +
1.217 + If no aRoot is provided, the entire DOM tree is serialized. aRoot does not
1.218 + need to be owned by this document.
1.219 +
1.220 + @param aRFs An open file Server session
1.221 + @param aFileName A file name (with path)
1.222 + @param aRoot Root node to be serialized
1.223 + @param aSaveOptions Options that control how serialization is performed
1.224 + @return Number of bytes written
1.225 + @leave KXmlEngErrWrongEncoding Encoding not understood
1.226 + @leave KXmlEngErrWrongUseOfAPI Document is NULL
1.227 + @leave KXmlEngErrNegativeOutputSize The data to be serialized has a negative size
1.228 + @leave - One of the system-wide error codes
1.229 + */
1.230 IMPORT_C TInt SaveL( RFs& aRFs,
1.231 const TDesC& aFileName,
1.232 TXmlEngNode aRoot = TXmlEngNode(),
1.233 const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions() ) const;
1.234
1.235 - /**
1.236 - * Serializes a document tree into provided output stream, which supports progressive writing of data.
1.237 - * For nodes containing binary data in the form of BinaryDataContainer, FileContainer or ChunkContainer,
1.238 - * client can implement custom serialization by implementing the interface MXmlEngDataSerializer and specify
1.239 - * the pointer in iDataSerializer member of aSaveOptions parameter. If no custom serialization is specified,
1.240 - * the binary data container nodes are serialized like text nodes.
1.241 - *
1.242 - * @since S60 v3.1
1.243 - * @param aStream An output stream to write serialized DOM tree
1.244 - * @param aRoot Root node to be serialized
1.245 - * @param aSaveOptions Options that control how serialization is performed
1.246 - * @return Number of byte written
1.247 - * @leave KXmlEngErrWrongUseOfAPI or one of general codes (e.g.KErrNoMemory)
1.248 - * @see MXmlEngOutputStream
1.249 - */
1.250 + /**
1.251 + Serializes document tree into provided output stream, which supports
1.252 + progressive writing of data. For nodes containing binary data in the form
1.253 + of BinaryDataContainer, FileContainer or ChunkContainer, the client can
1.254 + implement custom serialization by implementing the MXmlEngDataSerializer
1.255 + interface and saving a pointer to the customer serializer in the
1.256 + iDataSerializer member of the aSaveOptions parameter. If no custom
1.257 + serialization is specified, the binary data container nodes are serialized
1.258 + like text nodes.
1.259 +
1.260 + If no aRoot is provided, the entire DOM tree is serialized. aRoot does not
1.261 + need to be owned by this document.
1.262 +
1.263 + @param aStream An output stream to write the serialized DOM tree
1.264 + @param aRoot Root node to be serialized
1.265 + @param aSaveOptions Options that control how serialization is performed
1.266 + @return Number of bytes written
1.267 + @leave KXmlEngErrWrongEncoding Encoding not understood
1.268 + @leave KXmlEngErrWrongUseOfAPI Document is NULL
1.269 + @leave KXmlEngErrNegativeOutputSize The data to be serialized has a negative size
1.270 + @leave - One of the system-wide error codes
1.271 + */
1.272 IMPORT_C TInt SaveL( MXmlEngOutputStream& aStream,
1.273 TXmlEngNode aRoot = TXmlEngNode(),
1.274 const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions() ) const;
1.275
1.276 /**
1.277 - * Saves document tree into memory buffer
1.278 - *
1.279 - * @since S60 v3.1
1.280 - * @param aBuffer Resulting buffer
1.281 - * @param aRoot A "root" of the subtree to serialize
1.282 - * @param aSaveOptions Various options to be effective during serialization
1.283 - * @return Number of bytes in updated buffer
1.284 - * @leave KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding.
1.285 - *
1.286 - * @note Result returned via aBuffer argument owns the memory buffer; it is up to
1.287 - * method caller to free it like in this sample:
1.288 - *
1.289 - * @see TXmlEngSerializationOptions
1.290 - */
1.291 + Saves document tree into memory buffer.
1.292 +
1.293 + Any existing contents in aBuffer will be deleted. The memory required for
1.294 + aBuffer will be allocated by this method. The method caller must Close()
1.295 + aBuffer.
1.296 +
1.297 + If no aRoot is provided, the entire DOM tree is serialized. aRoot does not
1.298 + need to be owned by this document.
1.299 +
1.300 + @param aBuffer Resulting buffer
1.301 + @param aRoot The root of the subtree to serialize
1.302 + @param aSaveOptions Options that control how serialization is performed
1.303 + @return Size of buffer
1.304 + @leave KXmlEngErrWrongEncoding Encoding not understood
1.305 + @leave KXmlEngErrWrongUseOfAPI Document is NULL
1.306 + @leave KXmlEngErrNegativeOutputSize The data to be serialized has a negative size
1.307 + @leave - One of the system-wide error codes
1.308 + */
1.309 IMPORT_C TInt SaveL(RBuf8& aBuffer,
1.310 TXmlEngNode aRoot = TXmlEngNode(),
1.311 const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions()) const;
1.312
1.313 - /**
1.314 - * Creates complete copy of the document
1.315 - *
1.316 - * @since S60 v3.1
1.317 - * @return Complete copy of the document tree
1.318 - */
1.319 + /**
1.320 + Creates a complete copy of the document and transfers ownership to the
1.321 + caller. The caller is required to call Close() on the new document. The
1.322 + new document is independant from this document and this document may be
1.323 + changed or closed without affecting the new document.
1.324 +
1.325 + @return Complete copy of the document
1.326 + @leave - One of the system-wide error codes
1.327 + */
1.328 IMPORT_C RXmlEngDocument CloneDocumentL() const;
1.329
1.330 - /**
1.331 - * Creates new element from specific namespace to be a root of the document tree.
1.332 - * Any existing document element of the document is destroyed
1.333 - *
1.334 - * @since S60 v3.1
1.335 - * @param aName Element name
1.336 - * @param aNamespaceUri Element namespace URI
1.337 - * @param aPrefix Element namemespace prefix
1.338 - * @return A new root element
1.339 - */
1.340 + /**
1.341 + Creates a new element from a specific namespace to be the root of the
1.342 + document tree. Any existing document element of the document is destroyed.
1.343 +
1.344 + @param aName Element name
1.345 + @param aNamespaceUri Element namespace URI
1.346 + @param aPrefix Element namemespace prefix
1.347 + @return The new root element
1.348 + @leave KXmlEngErrWrongUseOfAPI No name has been specified
1.349 + @leave - One of the system-wide error codes
1.350 + */
1.351 IMPORT_C TXmlEngElement CreateDocumentElementL(const TDesC8& aName,
1.352 const TDesC8& aNamespaceUri = KNullDesC8,
1.353 const TDesC8& aPrefix = KNullDesC8);
1.354
1.355 - /**
1.356 - * Replaces (and destroys) document element with another one
1.357 - * New document element is added as the last child to the document node
1.358 - *
1.359 - * @since S60 v3.1
1.360 - * @param aNewDocElement New document tree
1.361 - *
1.362 - * @note Use TXmlEngElement::ReconcileNamespacesL() on the new document element
1.363 - * if it or its descendants can contain references to namespace declarations
1.364 - * out of the element
1.365 - * @see TXmlEngElement::ReconcileNamespacesL()
1.366 - */
1.367 + /**
1.368 + Replaces (and destroys) the document element.
1.369 +
1.370 + Note: Use TXmlEngElement::ReconcileNamespacesL() on the new document
1.371 + element if it or its descendants can contain references to namespace
1.372 + declarations outside of the element.
1.373 +
1.374 + @param aNewDocElement New document element
1.375 + @see TXmlEngElement::ReconcileNamespacesL()
1.376 + */
1.377 IMPORT_C void SetDocumentElement(TXmlEngElement aNewDocElement);
1.378
1.379 /**
1.380 - * Get document encoding
1.381 - *
1.382 - * @since S60 v3.1
1.383 - * @return Encoding of the source XML data.
1.384 - */
1.385 + Get document encoding.
1.386 + @return Encoding of the source XML data or TPtrC8("") if none.
1.387 + */
1.388 IMPORT_C TPtrC8 XmlEncoding() const;
1.389
1.390 /**
1.391 - * Get xml version
1.392 - *
1.393 - * @since S60 v3.1
1.394 - * @return Version number of XML taken from XML declaration
1.395 - */
1.396 + Get xml version
1.397 + @return Version number reported by the XML declaration or TPtrC8("") if none.
1.398 + */
1.399 IMPORT_C TPtrC8 XmlVersion() const;
1.400
1.401 /**
1.402 - * Retrieves base URI (if defined) of the document or NULL
1.403 - *
1.404 - * @since S60 v3.1
1.405 - * @return Document URI
1.406 - */
1.407 + Retrieves base URI (if defined) of the document
1.408 + @return Document URI or TPtrC8("") if none.
1.409 + */
1.410 IMPORT_C TPtrC8 DocumentUri() const;
1.411
1.412 /**
1.413 - * Check if document is standalone
1.414 - *
1.415 - * @since S60 v3.1
1.416 - * @return Whether standalone="true" was specified in XML declaration in the source XML file.
1.417 - */
1.418 - IMPORT_C TBool IsStandalone() const;
1.419 + Check if document is standalone
1.420 + @return ETrue if standalone="true" was specified in the XML declaration in
1.421 + the source XML file.
1.422 + */
1.423 + IMPORT_C TBool IsStandalone() const;
1.424
1.425 /**
1.426 - * Sets XML version number to be shown in XML declaration when document is serialized.
1.427 - *
1.428 - * @since S60 v3.1
1.429 - * @param aVersion New version
1.430 - */
1.431 + Sets XML version number to be shown in XML declaration when document is serialized.
1.432 + @param aVersion Version string
1.433 + @leave - One of the system-wide error codes
1.434 + */
1.435 IMPORT_C void SetXmlVersionL(const TDesC8& aVersion);
1.436
1.437 - /**
1.438 - * Sets location of the document.
1.439 - * Document's URI is used as top-level base URI definition.
1.440 - *
1.441 - * @since S60 v3.1
1.442 - * @param aUri New document URI
1.443 - */
1.444 + /**
1.445 + Sets the location of the document. The document's URI is used as the
1.446 + top-level base URI definition.
1.447 + @param aUri Document URI
1.448 + @leave - One of the system-wide error codes
1.449 + */
1.450 IMPORT_C void SetDocumentUriL(const TDesC8& aUri);
1.451
1.452 - /**
1.453 - * Sets 'standalone' attribute of XML declaration for a document
1.454 - *
1.455 - * @since S60 v3.1
1.456 - * @param aStandalone Is document standalone
1.457 - */
1.458 + /**
1.459 + Sets "standalone" attribute of XML declaration for the document
1.460 + @param aStandalone Is the document standalone
1.461 + */
1.462 IMPORT_C void SetStandalone(TBool aStandalone);
1.463
1.464 - /**
1.465 - * Get dom implementation.
1.466 - *
1.467 - * @since S60 v3.1
1.468 - * @return Object that represents current DOM implementation
1.469 - *
1.470 - * @note There is no practical use of implementation object in this version
1.471 - * of API other than for creating new RXmlEngDocument instances, but
1.472 - * it will change in the future, when an implementation object
1.473 - * is used for changing configuration settings at run-time.
1.474 - */
1.475 + /**
1.476 + Get the DOM implementation. Ownership is not transferred. Any operation
1.477 + on the returned object will affect this document directly, in particular,
1.478 + a call to RXmlEngDOMImplementation::Close() will cause further operations
1.479 + on this document to fail.
1.480 +
1.481 + @return Object that represents current DOM implementation
1.482 + */
1.483 IMPORT_C RXmlEngDOMImplementation Implementation() const;
1.484
1.485 /**
1.486 - * Get document element
1.487 - *
1.488 - * @since S60 v3.1
1.489 - * @return A document element - the top-most element in the document tree
1.490 - */
1.491 + Get the document element
1.492 + @return The document element -- the top-most element in the document tree
1.493 + */
1.494 IMPORT_C TXmlEngElement DocumentElement() const;
1.495
1.496 - /**
1.497 - * Sets "document" property on the node and all its descendants to be this RXmlEngDocument node
1.498 - *
1.499 - * @since S60 v3.1
1.500 - * @param aSource Node that should be added.
1.501 - * @return Adopted node
1.502 - */
1.503 + /**
1.504 + Sets the "document" property on the node and all its descendants to be this
1.505 + RXmlEngDocument node
1.506 + @param aSource Node that should be added.
1.507 + @return Adopted node
1.508 + @leave KXmlEngErrWrongUseOfAPI The node has a parent node, the node is
1.509 + already owned by this document, or the node is a document.
1.510 + @leave - One of the system-wide error codes
1.511 + */
1.512 IMPORT_C TXmlEngNode AdoptNodeL(TXmlEngNode aSource);
1.513
1.514 /**
1.515 - * Creates new attribute,
1.516 - *
1.517 - * @since S60 v3.1
1.518 - * @param aName Name of the atribute; no prefix allowed
1.519 - * @param aValue Value of the attribute (optional)
1.520 - * @return Handler to the newly created attribute
1.521 - *
1.522 - * @note
1.523 - * aValue should represent a correct value of an attribute if it is put as is into XML file
1.524 - * (with all characters correctly escaped with entity references when XML spec requires)
1.525 - *
1.526 - * TXmlEngElement class provides a rich set of attribute creation methods, which not
1.527 - * just create attribute but also link it into element.
1.528 - *
1.529 - * There is no way to create attributes with namespace (despite the DOM spec);
1.530 - * you have to use one of the TXmlEngElement::AddNewAttributeL(..) methods instead
1.531 - *
1.532 - * Returned handler is the only reference to the allocated memory
1.533 - * until you have attached the attribute to some element node
1.534 - */
1.535 + Creates a new attribute.
1.536 +
1.537 + aValue should represent the correct value of an attribute if it is put
1.538 + as-is into an XML file (with all characters correctly escaped with entity
1.539 + references when XML spec requires)
1.540 +
1.541 + The TXmlEngElement class provides a rich set of attribute creation methods,
1.542 + which not only create attributes but also link them into elements.
1.543 +
1.544 + @see TXmlEngElement
1.545 +
1.546 + There is no way to create attributes with namespaces (despite the DOM spec);
1.547 + you have to use one of the TXmlEngElement::AddNewAttributeL(..) methods instead
1.548 +
1.549 + The returned attribute is the only reference to the allocated memory until
1.550 + you have attached the attribute to some element node.
1.551 +
1.552 + @param aName Name of the atribute; no prefix allowed
1.553 + @param aValue Value of the attribute (optional)
1.554 + @return The newly created attribute
1.555 + @leave KXmlEngErrWrongUseOfAPI No name specified
1.556 + @leave - One of the system-wide error codes
1.557 + */
1.558 IMPORT_C TXmlEngAttr CreateAttributeL(const TDesC8& aName,
1.559 const TDesC8& aValue = KNullDesC8);
1.560
1.561 /**
1.562 - * Creates new text node and copies the content string into it.
1.563 - *
1.564 - * @since S60 v3.1
1.565 - * @param aCharacters Text node content
1.566 - * @return Created node
1.567 - */
1.568 + Creates a new text node and copies the content string into it.
1.569 + @param aCharacters Text node content
1.570 + @return The created node
1.571 + @leave - One of the system-wide error codes
1.572 + */
1.573 IMPORT_C TXmlEngTextNode CreateTextNodeL(const TDesC8& aCharacters = KNullDesC8);
1.574
1.575 - /**
1.576 - * Creates new binary container and copies the content string into it.
1.577 - * Pointer to the container is stored in the document's
1.578 - * data container list that can be fetched using GetDataContainerList().
1.579 - * @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )
1.580 - *
1.581 - * @since S60 v3.2
1.582 - * @param aCid Content identifier
1.583 - * @param aData Binary octets
1.584 - * @return Created node
1.585 - */
1.586 + /**
1.587 + Creates a new binary container and copies the specified cid and data into
1.588 + it. A pointer to the container is stored in the document's data container
1.589 + list that can be fetched using GetDataContainerList().
1.590 +
1.591 + @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )
1.592 + @param aCid Content identifier
1.593 + @param aData Binary octets
1.594 + @return The new binary container
1.595 + @leave - One of the system-wide error codes
1.596 + */
1.597 IMPORT_C TXmlEngBinaryContainer CreateBinaryContainerL( const TDesC8& aCid,
1.598 const TDesC8& aData );
1.599
1.600 - /**
1.601 - * Creates new chunk container that stores reference to
1.602 - * memory chunk.
1.603 - * Pointer to the container is stored in the document's
1.604 - * data container list that can be fetched using GetDataContainerList().
1.605 - * @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )
1.606 - *
1.607 - * @since S60 v3.2
1.608 - * @param aCid Content identifier
1.609 - * @param aChunk RChunk reference
1.610 - * @param aChunkOffset Offset to the binary data in aChunk
1.611 - * @param aDataSize Size of binary data in aChunk
1.612 - * @return Created node
1.613 - */
1.614 + /**
1.615 + Creates a new chunk container and copies the specified cid into it. A
1.616 + reference to a memory chunk is stored in the container. The memory chunk
1.617 + must stay in scope for the lifetime of the container. A pointer to the
1.618 + container is stored in the document's data container list that can be
1.619 + fetched using GetDataContainerList().
1.620 +
1.621 + @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )
1.622 + @param aCid Content identifier
1.623 + @param aChunk RChunk reference
1.624 + @param aChunkOffset Offset to the binary data in aChunk
1.625 + @param aDataSize Size of binary data in aChunk
1.626 + @return The new chunk container
1.627 + @leave - One of the system-wide error codes
1.628 + */
1.629 IMPORT_C TXmlEngChunkContainer CreateChunkContainerL( const TDesC8& aCid,
1.630 const RChunk& aChunk,
1.631 const TInt aChunkOffset,
1.632 const TInt aDataSize );
1.633
1.634 - /**
1.635 - * Creates new file container that stores reference to
1.636 - * file in file system.
1.637 - * Pointer to the container is stored in the document's
1.638 - * data container list that can be fetched using GetDataContainerList().
1.639 - * @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )
1.640 - *
1.641 - * @since S60 v3.2
1.642 - * @param aCid Content identifier
1.643 - * @param aFile RFile reference
1.644 - * @return Created node
1.645 - */
1.646 + /**
1.647 + Creates a new file container and copies the specified cid into it. A
1.648 + reference to a file is stored in the container. aFile must stay in scope
1.649 + of the lifetime of the container. A pointer to the container is stored in
1.650 + the document's data container list that can be fetched using
1.651 + GetDataContainerList().
1.652 +
1.653 + @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )
1.654 + @param aCid Content identifier
1.655 + @param aFile The file to reference
1.656 + @return The new file container
1.657 + @leave - One of the system-wide error codes
1.658 + */
1.659 IMPORT_C TXmlEngFileContainer CreateFileContainerL( const TDesC8& aCid,
1.660 const RFile& aFile );
1.661
1.662 - /**
1.663 - * Creates new element node that belongs to specific namespace.
1.664 - * A namespace declaration node is created on the element.
1.665 - *
1.666 - * @since S60 v3.1
1.667 - * @param aNamespaceUri Namespace of new element
1.668 - * @param aPrefix Prefix to use for namespace binding and QName of the element
1.669 - * @param aLocalName Local name of the element
1.670 - * @return Created node
1.671 - * @note If null namespace uri is provided element will be created without namespace.
1.672 - */
1.673 + /**
1.674 + Creates a new element node that belongs to the specific namespace. A
1.675 + namespace declaration node is created on the element.
1.676 +
1.677 + If the provided namespace uri is NULL, the element will be created without
1.678 + namespace.
1.679 +
1.680 + @param aNamespaceUri Namespace of new element
1.681 + @param aPrefix Prefix to use for the namespace binding and the QName of the element
1.682 + @param aLocalName Local name of the element
1.683 + @return The created element
1.684 + @leave KXmlEngErrWrongUseOfAPI No name specified
1.685 + @leave - One of the system-wide error codes
1.686 + */
1.687 IMPORT_C TXmlEngElement CreateElementL(const TDesC8& aLocalName,
1.688 const TDesC8& aNamespaceUri = KNullDesC8,
1.689 const TDesC8& aPrefix = KNullDesC8);
1.690
1.691 /**
1.692 - * Creates new comment node and copies the content string into it.
1.693 - *
1.694 - * @since S60 v3.1
1.695 - * @param aText New comment
1.696 - * @return Created node
1.697 - */
1.698 + Creates a new comment node and copies the specified string into it.
1.699 + @param aText New comment
1.700 + @return The created node
1.701 + @leave - One of the system-wide error codes
1.702 + */
1.703 IMPORT_C TXmlEngComment CreateCommentL(const TDesC8& aText = KNullDesC8);
1.704
1.705 /**
1.706 - * Creates new CDATA section node and copies the content into it.
1.707 - *
1.708 - * @since S60 v3.1
1.709 - * @param aContents CDATASection content
1.710 - * @return Created node
1.711 - */
1.712 + Creates a new CDATA section node and copies the specified string into it.
1.713 + @param aContents CDATASection content
1.714 + @return The created node
1.715 + @leave - One of the system-wide error codes
1.716 + */
1.717 IMPORT_C TXmlEngCDATASection CreateCDATASectionL(const TDesC8& aContents = KNullDesC8);
1.718
1.719 /**
1.720 - * Creates new entity reference node for aEntityName entity
1.721 - *
1.722 - * @since S60 v3.1
1.723 - * @param aEntityRef is a string in one of the forms:
1.724 - * - <i>name</i>
1.725 - * - <b>&</b><i>name</i>
1.726 - * - <b>&</b><i>name</i><b>;</b>
1.727 - * where <i>name</i> is the name of the entity
1.728 - * @return Created node
1.729 - *
1.730 - * @note < , > , ' , " and other <b>predefined</b> entity references
1.731 - * should not be created with this method. These entity refs are rather
1.732 - * "character references" and encoded/decoded automatically.
1.733 - */
1.734 + Creates a new entity reference node and copies the specified string into
1.735 + it.
1.736 +
1.737 + Note: < , > , ' , " and other predefined entity references
1.738 + should not be created with this method. These entity references are rather
1.739 + "character references" and are encoded/decoded automatically.
1.740 +
1.741 + @param aEntityRef is a string in one of these forms:
1.742 + - name
1.743 + - &name
1.744 + - &name;
1.745 + where name is the name of the entity
1.746 + @return The new entity reference
1.747 + @leave KXmlEngErrWrongUseOfAPI No entity specified
1.748 + @leave - One of the system-wide error codes
1.749 + */
1.750 IMPORT_C TXmlEngEntityReference CreateEntityReferenceL(const TDesC8& aEntityRef);
1.751
1.752 /**
1.753 - * Creates new processing instruction node and set its "target" and "data" values
1.754 - *
1.755 - * @since S60 v3.1
1.756 - * @param aTarget Target
1.757 - * @param aData Data
1.758 - * @return Created node
1.759 - */
1.760 + Creates a new empty Document Fragment node. The document fragment is owned by
1.761 + this document.
1.762 + @return The created document fragment
1.763 + @leave - One of the system-wide error codes
1.764 + */
1.765 + IMPORT_C TXmlEngDocumentFragment CreateDocumentFragmentL();
1.766 +
1.767 + /**
1.768 + Creates a new processing instruction node and copies "target" and "data"
1.769 + into it.
1.770 +
1.771 + @param aTarget Target
1.772 + @param aData Data
1.773 + @return The created processing instruction
1.774 + @leave KXmlEngErrWrongUseOfAPI No target specified
1.775 + @leave - One of the system-wide error codes
1.776 + */
1.777 IMPORT_C TXmlEngProcessingInstruction CreateProcessingInstructionL(const TDesC8& aTarget,
1.778 const TDesC8& aData = KNullDesC8);
1.779
1.780 - /**
1.781 - * Registers specified attribute as xml:id.
1.782 - * First parametr allows user, to specify sub-tree, not to search whole document.
1.783 - * To search whole tree see @see RegisterXmlId(const TDesC8,const TDesC8)
1.784 - *
1.785 - * @since S60 v3.2
1.786 - * @param aStartElement Root of tree to search (should be part of the document)
1.787 - * @param aLocalName Name of attribute
1.788 - * @param aNamespaceUri Namespace of new element (default empty)
1.789 - */
1.790 + /**
1.791 + Sets the specified attribute as a xml:id attribute, starting at
1.792 + aStartElement and recursing through the subtree. To set the specified
1.793 + attribute as a xml:id attribute for the entire DOM tree, see
1.794 + RegisterXmlId(const TDesC8&,const TDesC8&).
1.795 +
1.796 + @param aStartElement Root of the subtree to recurse
1.797 + @param aLocalName Name of the attribute
1.798 + @param aNamespaceUri Namespace of the new element (default empty)
1.799 + @leave KXmlEngErrWrongUseOfAPI The starting element is NULL, the attribute
1.800 + name is not specified, the starting element is the document, or the
1.801 + starting element does not belong to a document.
1.802 + @leave KErrAlreadyExists The attribute is already set to be xml:id
1.803 + @leave - One of the system-wide error codes
1.804 + */
1.805 IMPORT_C void RegisterXmlIdL(TXmlEngElement aStartElement,
1.806 const TDesC8& aLocalName,
1.807 const TDesC8& aNamespaceUri = KNullDesC8);
1.808
1.809 - /**
1.810 - * Registers specified attribute as xml:id.
1.811 - * Not to search whole tree see @see RegisterXmlId(TXmlEngElement,const TDesC8,const TDesC8)
1.812 - *
1.813 - * @since S60 v3.2
1.814 - * @param aLocalName Name of attribute
1.815 - * @param aNamespaceUri Namespace of new element (default empty)
1.816 - */
1.817 + /**
1.818 + Sets the specified attribute as a xml:id attribute, recursing through the
1.819 + entire DOM tree. In order to specify a subtree only, see
1.820 + RegisterXmlId(TXmlEngElement,const TDesC8,const TDesC8).
1.821 +
1.822 + @param aLocalName Name of attribute
1.823 + @param aNamespaceUri Namespace of new element (default empty)
1.824 + @leave KXmlEngErrWrongUseOfAPI The document is NULL
1.825 + @leave KErrAlreadyExists The attribute is already set to be xml:id
1.826 + @leave - One of the system-wide error codes
1.827 + */
1.828 IMPORT_C void RegisterXmlIdL(const TDesC8& aLocalName,
1.829 const TDesC8& aNamespaceUri = KNullDesC8);
1.830
1.831 /**
1.832 - * Looks for element with specified value of xml:id
1.833 - *
1.834 - * @since S60 v3.2
1.835 - * @param aValue Name of attribute
1.836 - * @return found element or null-element.
1.837 - */
1.838 + Looks for an element with the specified xml:id attribute
1.839 + @param aValue Name of attribute
1.840 + @return The found element or a NULL element if not found
1.841 + @leave - One of the system-wide error codes
1.842 + */
1.843 IMPORT_C TXmlEngElement FindElementByXmlIdL(const TDesC8& aValue ) const;
1.844
1.845 /**
1.846 - * Retrieves an array of data containers owned by this document.
1.847 - *
1.848 - * @note The document ceases to be the owner of data container when data container
1.849 - * (or one of its predecessors) is removed from the document or data container
1.850 - * (or one of its predecessors) becomes a part of another document.
1.851 - * Unlinking data container (or one of its predecessors) doesn't remove
1.852 - * ownership of data container from the this document so the list might
1.853 - * contain containers that are not linked to this document anymore.
1.854 - * @since S60 v3.2
1.855 - * @param aList Array of data containers
1.856 - */
1.857 - IMPORT_C void GetDataContainerList( RArray<TXmlEngDataContainer>& aList );
1.858 + Retrieves an array of data containers owned by this document.
1.859 +
1.860 + Note: The document ceases to be the owner of a data container when the data
1.861 + container (or one of its predecessors) is removed from the document or
1.862 + becomes part of another document. Unlinking a data container (or one of its
1.863 + predecessors) doesn't remove ownership of the data container from this
1.864 + document so the list might contain containers that are not linked to this
1.865 + document anymore.
1.866 +
1.867 + @param aList Array of data containers
1.868 + @return KErrNone if successful or one of the system wide error codes otherwise
1.869 + */
1.870 + IMPORT_C TInt GetDataContainerList( RArray<TXmlEngDataContainer>& aList );
1.871
1.872 protected:
1.873 friend class RXmlEngDOMParser;
1.874 @@ -483,81 +521,40 @@
1.875
1.876 protected:
1.877 /**
1.878 - * Constructor
1.879 - *
1.880 - * @since S60 v3.1
1.881 - * @param aInternal Document pointer
1.882 - */
1.883 + Constructor
1.884 + @param aInternal Document pointer
1.885 + */
1.886 inline RXmlEngDocument(void* aInternal);
1.887
1.888 /**
1.889 - * DISABLED for document; CloneDocumentL() must be used
1.890 - *
1.891 - * @since S60 v3.1
1.892 - */
1.893 + DISABLED for document; CloneDocumentL() must be used
1.894 + */
1.895 inline TXmlEngNode CopyL() const;
1.896
1.897 /**
1.898 - * DISABLED for document; Destroy() must be used
1.899 - *
1.900 - * @since S60 v3.1
1.901 - */
1.902 + DISABLED for document; Close() must be used
1.903 + */
1.904 inline void Remove();
1.905
1.906 /**
1.907 - * DISABLED for document; Destroy() must be used
1.908 - *
1.909 - * @since S60 v3.1
1.910 + DISABLED for document; Close() must be used
1.911 + */
1.912 + inline void ReplaceWith(TXmlEngNode aNode);
1.913 + inline void ReplaceWithL(TXmlEngNode aNode);
1.914 +
1.915 + /**
1.916 + DISABLED for document; Close() must be used
1.917 */
1.918 - inline void ReplaceWith(TXmlEngNode aNode);
1.919 + inline TXmlEngNode SubstituteForL(TXmlEngNode aNode);
1.920 +
1.921 private:
1.922 - /**
1.923 - * Main implementation of SaveL() functions that puts together all common code
1.924 - * and serializes to buffer or output stream.
1.925 - *
1.926 - * @since S60 v3.2
1.927 - * @param aNode Root node to be serialized
1.928 - * @param aBuffer buffer with serialized data.
1.929 - * @param aOutputStream stream that should be used during serialization
1.930 - * @param aSaveOptions Options that control how serialization is performed
1.931 - * @return Number of bytes written
1.932 - * @leave KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding, KErrDiskFull.
1.933 - */
1.934 TInt SaveNodeL( TXmlEngNode aNode,
1.935 RBuf8& aBuffer,
1.936 MXmlEngOutputStream* aOutputStream = NULL,
1.937 TXmlEngSerializationOptions aOpt = TXmlEngSerializationOptions()) const;
1.938
1.939 - /**
1.940 - * "Secondary" constructor that should be called on every newly created document node.
1.941 - * Initializes container for nodes owned by the document.
1.942 - *
1.943 - * The need for such secondary constructor is in the fact that underlying libxml2
1.944 - * library knows nothing about ownership of unlinked nodes -- this feature is
1.945 - * implemented in C++ DOM wrapper.
1.946 - *
1.947 - * @since S60 v3.1
1.948 - */
1.949 void InitOwnedNodeListL();
1.950 -
1.951 - /**
1.952 - * Adds aNode to the list of owned nodes - the nodes that are not linked yet into a
1.953 - * document tree, but still destroyed with the document that owns them.
1.954 - *
1.955 - * @since S60 v3.1
1.956 - * @param aNode Node that should be added to document
1.957 - *
1.958 - * In case of OOM (during growing node list container) the argument node is freed with
1.959 - * xmlFreeNode()
1.960 - */
1.961 void TakeOwnership(TXmlEngNode aNode);
1.962 -
1.963 - /**
1.964 - * Remove aNode from the list of owned nodes.
1.965 - *
1.966 - * @since S60 v3.1
1.967 - * @param aNode Node that should be removed from document
1.968 - */
1.969 void RemoveOwnership(TXmlEngNode aNode);
1.970
1.971 protected:
1.972 @@ -568,6 +565,6 @@
1.973
1.974
1.975
1.976 -#include "xmlengdocument.inl"
1.977 +#include <xml/dom/xmlengdocument.inl>
1.978
1.979 -#endif /* XMLENGINE_DOCUMENT_H_INCLUDED */
1.980 +#endif /* XMLENGDOCUMENT_H */