/*
* 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: Document node functions
*
*/
#ifndef XMLENGINE_DOCUMENT_H_INCLUDED
#define XMLENGINE_DOCUMENT_H_INCLUDED
#include <f32file.h>
#include "xmlengnode.h"
#include "xmlengserializationoptions.h"
// FORWARD DECLARATION
class RXmlEngDOMImplementation;
/**
* Instance of RXmlEngDocument class represents an XML document in the DOM tree.
*
* Is a storage all nodes and information about XML data.
*
* @lib XmlEngineDOM.lib
* @since S60 v3.1
*/
class RXmlEngDocument : public TXmlEngNode
{
public:
/**
* Default constructor.
*
* Instance of RXmlEngDocument must be "opened" with one of OpenL() overloads.
*
* @since S60 v3.1
*/
IMPORT_C RXmlEngDocument();
/**
* Opens the document.
*
* @since S60 v3.2
* @param aDOMImpl DOM implementation object
* @return KErrNone if succeed.
*/
IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl);
/**
* Opens the document.
*
* @since S60 v3.2
* @param aDOMImpl DOM implementation object
* @param aInternal Document pointer
* @return KErrNone if succeed.
*/
IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl, void* aInternal);
/**
* Opens the document.
*
* @since S60 v3.2
* @param aDOMImpl DOM implementation object
* @param aRoot element taht will be root of the DOM tree
* @return KErrNone if succeed.
*/
IMPORT_C void OpenL(RXmlEngDOMImplementation& aDOMImpl, TXmlEngElement aRoot);
/**
* Closes document
*
* @since S60 v3.1
*/
IMPORT_C void Close();
/**
* Serializes document tree into a file. For nodes containing binary data in the form of BinaryDataContainer,
* FileContainer or ChunkContainer, client can implement custom serialization by implementing the interface
* MXmlEngDataSerializer and specify the pointer in iDataSerializer member of aSaveOptions parameter. If no
* custom serialization is specified, the binary data container nodes are serialized like text nodes.
*
* @since S60 v3.2
* @param aFileName A file name (with path)
* @param aRoot Root node to be serialized
* @param aSaveOptions Options that control how serialization is performed
* @return Number of byte written
* @leave KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding, KErrDiskFull.
*/
IMPORT_C TInt SaveL( const TDesC& aFileName,
TXmlEngNode aRoot = TXmlEngNode(),
const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions() ) const;
/**
* Serializes document tree into a file. For nodes containing binary data in the form of BinaryDataContainer,
* FileContainer or ChunkContainer, client can implement custom serialization by implementing the interface
* MXmlEngDataSerializer and specify the pointer in iDataSerializer member of aSaveOptions parameter. If no
* custom serialization is specified, the binary data container nodes are serialized like text nodes.
*
* @since S60 v3.2
* @param aRFs File Server session
* @param aFileName A file name (with path)
* @param aRoot Root node to be serialized
* @param aSaveOptions Options that control how serialization is performed
* @return Number of byte written
* @leave KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding, KErrDiskFull.
*/
IMPORT_C TInt SaveL( RFs& aRFs,
const TDesC& aFileName,
TXmlEngNode aRoot = TXmlEngNode(),
const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions() ) const;
/**
* Serializes a document tree into provided output stream, which supports progressive writing of data.
* For nodes containing binary data in the form of BinaryDataContainer, FileContainer or ChunkContainer,
* client can implement custom serialization by implementing the interface MXmlEngDataSerializer and specify
* the pointer in iDataSerializer member of aSaveOptions parameter. If no custom serialization is specified,
* the binary data container nodes are serialized like text nodes.
*
* @since S60 v3.1
* @param aStream An output stream to write serialized DOM tree
* @param aRoot Root node to be serialized
* @param aSaveOptions Options that control how serialization is performed
* @return Number of byte written
* @leave KXmlEngErrWrongUseOfAPI or one of general codes (e.g.KErrNoMemory)
* @see MXmlEngOutputStream
*/
IMPORT_C TInt SaveL( MXmlEngOutputStream& aStream,
TXmlEngNode aRoot = TXmlEngNode(),
const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions() ) const;
/**
* Saves document tree into memory buffer
*
* @since S60 v3.1
* @param aBuffer Resulting buffer
* @param aRoot A "root" of the subtree to serialize
* @param aSaveOptions Various options to be effective during serialization
* @return Number of bytes in updated buffer
* @leave KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding.
*
* @note Result returned via aBuffer argument owns the memory buffer; it is up to
* method caller to free it like in this sample:
*
* @see TXmlEngSerializationOptions
*/
IMPORT_C TInt SaveL(RBuf8& aBuffer,
TXmlEngNode aRoot = TXmlEngNode(),
const TXmlEngSerializationOptions& aSaveOptions = TXmlEngSerializationOptions()) const;
/**
* Creates complete copy of the document
*
* @since S60 v3.1
* @return Complete copy of the document tree
*/
IMPORT_C RXmlEngDocument CloneDocumentL() const;
/**
* Creates new element from specific namespace to be a root of the document tree.
* Any existing document element of the document is destroyed
*
* @since S60 v3.1
* @param aName Element name
* @param aNamespaceUri Element namespace URI
* @param aPrefix Element namemespace prefix
* @return A new root element
*/
IMPORT_C TXmlEngElement CreateDocumentElementL(const TDesC8& aName,
const TDesC8& aNamespaceUri = KNullDesC8,
const TDesC8& aPrefix = KNullDesC8);
/**
* Replaces (and destroys) document element with another one
* New document element is added as the last child to the document node
*
* @since S60 v3.1
* @param aNewDocElement New document tree
*
* @note Use TXmlEngElement::ReconcileNamespacesL() on the new document element
* if it or its descendants can contain references to namespace declarations
* out of the element
* @see TXmlEngElement::ReconcileNamespacesL()
*/
IMPORT_C void SetDocumentElement(TXmlEngElement aNewDocElement);
/**
* Get document encoding
*
* @since S60 v3.1
* @return Encoding of the source XML data.
*/
IMPORT_C TPtrC8 XmlEncoding() const;
/**
* Get xml version
*
* @since S60 v3.1
* @return Version number of XML taken from XML declaration
*/
IMPORT_C TPtrC8 XmlVersion() const;
/**
* Retrieves base URI (if defined) of the document or NULL
*
* @since S60 v3.1
* @return Document URI
*/
IMPORT_C TPtrC8 DocumentUri() const;
/**
* Check if document is standalone
*
* @since S60 v3.1
* @return Whether standalone="true" was specified in XML declaration in the source XML file.
*/
IMPORT_C TBool IsStandalone() const;
/**
* Sets XML version number to be shown in XML declaration when document is serialized.
*
* @since S60 v3.1
* @param aVersion New version
*/
IMPORT_C void SetXmlVersionL(const TDesC8& aVersion);
/**
* Sets location of the document.
* Document's URI is used as top-level base URI definition.
*
* @since S60 v3.1
* @param aUri New document URI
*/
IMPORT_C void SetDocumentUriL(const TDesC8& aUri);
/**
* Sets 'standalone' attribute of XML declaration for a document
*
* @since S60 v3.1
* @param aStandalone Is document standalone
*/
IMPORT_C void SetStandalone(TBool aStandalone);
/**
* Get dom implementation.
*
* @since S60 v3.1
* @return Object that represents current DOM implementation
*
* @note There is no practical use of implementation object in this version
* of API other than for creating new RXmlEngDocument instances, but
* it will change in the future, when an implementation object
* is used for changing configuration settings at run-time.
*/
IMPORT_C RXmlEngDOMImplementation Implementation() const;
/**
* Get document element
*
* @since S60 v3.1
* @return A document element - the top-most element in the document tree
*/
IMPORT_C TXmlEngElement DocumentElement() const;
/**
* Sets "document" property on the node and all its descendants to be this RXmlEngDocument node
*
* @since S60 v3.1
* @param aSource Node that should be added.
* @return Adopted node
*/
IMPORT_C TXmlEngNode AdoptNodeL(TXmlEngNode aSource);
/**
* Creates new attribute,
*
* @since S60 v3.1
* @param aName Name of the atribute; no prefix allowed
* @param aValue Value of the attribute (optional)
* @return Handler to the newly created attribute
*
* @note
* aValue should represent a correct value of an attribute if it is put as is into XML file
* (with all characters correctly escaped with entity references when XML spec requires)
*
* TXmlEngElement class provides a rich set of attribute creation methods, which not
* just create attribute but also link it into element.
*
* There is no way to create attributes with namespace (despite the DOM spec);
* you have to use one of the TXmlEngElement::AddNewAttributeL(..) methods instead
*
* Returned handler is the only reference to the allocated memory
* until you have attached the attribute to some element node
*/
IMPORT_C TXmlEngAttr CreateAttributeL(const TDesC8& aName,
const TDesC8& aValue = KNullDesC8);
/**
* Creates new text node and copies the content string into it.
*
* @since S60 v3.1
* @param aCharacters Text node content
* @return Created node
*/
IMPORT_C TXmlEngTextNode CreateTextNodeL(const TDesC8& aCharacters = KNullDesC8);
/**
* Creates new binary container and copies the content string into it.
* Pointer to the container is stored in the document's
* data container list that can be fetched using GetDataContainerList().
* @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )
*
* @since S60 v3.2
* @param aCid Content identifier
* @param aData Binary octets
* @return Created node
*/
IMPORT_C TXmlEngBinaryContainer CreateBinaryContainerL( const TDesC8& aCid,
const TDesC8& aData );
/**
* Creates new chunk container that stores reference to
* memory chunk.
* Pointer to the container is stored in the document's
* data container list that can be fetched using GetDataContainerList().
* @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )
*
* @since S60 v3.2
* @param aCid Content identifier
* @param aChunk RChunk reference
* @param aChunkOffset Offset to the binary data in aChunk
* @param aDataSize Size of binary data in aChunk
* @return Created node
*/
IMPORT_C TXmlEngChunkContainer CreateChunkContainerL( const TDesC8& aCid,
const RChunk& aChunk,
const TInt aChunkOffset,
const TInt aDataSize );
/**
* Creates new file container that stores reference to
* file in file system.
* Pointer to the container is stored in the document's
* data container list that can be fetched using GetDataContainerList().
* @see GetDataContainerList( RArray<TXmlEngDataContainer>& aList )
*
* @since S60 v3.2
* @param aCid Content identifier
* @param aFile RFile reference
* @return Created node
*/
IMPORT_C TXmlEngFileContainer CreateFileContainerL( const TDesC8& aCid,
const RFile& aFile );
/**
* Creates new element node that belongs to specific namespace.
* A namespace declaration node is created on the element.
*
* @since S60 v3.1
* @param aNamespaceUri Namespace of new element
* @param aPrefix Prefix to use for namespace binding and QName of the element
* @param aLocalName Local name of the element
* @return Created node
* @note If null namespace uri is provided element will be created without namespace.
*/
IMPORT_C TXmlEngElement CreateElementL(const TDesC8& aLocalName,
const TDesC8& aNamespaceUri = KNullDesC8,
const TDesC8& aPrefix = KNullDesC8);
/**
* Creates new comment node and copies the content string into it.
*
* @since S60 v3.1
* @param aText New comment
* @return Created node
*/
IMPORT_C TXmlEngComment CreateCommentL(const TDesC8& aText = KNullDesC8);
/**
* Creates new CDATA section node and copies the content into it.
*
* @since S60 v3.1
* @param aContents CDATASection content
* @return Created node
*/
IMPORT_C TXmlEngCDATASection CreateCDATASectionL(const TDesC8& aContents = KNullDesC8);
/**
* Creates new entity reference node for aEntityName entity
*
* @since S60 v3.1
* @param aEntityRef is a string in one of the forms:
* - <i>name</i>
* - <b>&</b><i>name</i>
* - <b>&</b><i>name</i><b>;</b>
* where <i>name</i> is the name of the entity
* @return Created node
*
* @note < , > , ' , " and other <b>predefined</b> entity references
* should not be created with this method. These entity refs are rather
* "character references" and encoded/decoded automatically.
*/
IMPORT_C TXmlEngEntityReference CreateEntityReferenceL(const TDesC8& aEntityRef);
/**
* Creates new processing instruction node and set its "target" and "data" values
*
* @since S60 v3.1
* @param aTarget Target
* @param aData Data
* @return Created node
*/
IMPORT_C TXmlEngProcessingInstruction CreateProcessingInstructionL(const TDesC8& aTarget,
const TDesC8& aData = KNullDesC8);
/**
* Registers specified attribute as xml:id.
* First parametr allows user, to specify sub-tree, not to search whole document.
* To search whole tree see @see RegisterXmlId(const TDesC8,const TDesC8)
*
* @since S60 v3.2
* @param aStartElement Root of tree to search (should be part of the document)
* @param aLocalName Name of attribute
* @param aNamespaceUri Namespace of new element (default empty)
*/
IMPORT_C void RegisterXmlIdL(TXmlEngElement aStartElement,
const TDesC8& aLocalName,
const TDesC8& aNamespaceUri = KNullDesC8);
/**
* Registers specified attribute as xml:id.
* Not to search whole tree see @see RegisterXmlId(TXmlEngElement,const TDesC8,const TDesC8)
*
* @since S60 v3.2
* @param aLocalName Name of attribute
* @param aNamespaceUri Namespace of new element (default empty)
*/
IMPORT_C void RegisterXmlIdL(const TDesC8& aLocalName,
const TDesC8& aNamespaceUri = KNullDesC8);
/**
* Looks for element with specified value of xml:id
*
* @since S60 v3.2
* @param aValue Name of attribute
* @return found element or null-element.
*/
IMPORT_C TXmlEngElement FindElementByXmlIdL(const TDesC8& aValue ) const;
/**
* Retrieves an array of data containers owned by this document.
*
* @note The document ceases to be the owner of data container when data container
* (or one of its predecessors) is removed from the document or data container
* (or one of its predecessors) becomes a part of another document.
* Unlinking data container (or one of its predecessors) doesn't remove
* ownership of data container from the this document so the list might
* contain containers that are not linked to this document anymore.
* @since S60 v3.2
* @param aList Array of data containers
*/
IMPORT_C void GetDataContainerList( RArray<TXmlEngDataContainer>& aList );
protected:
friend class RXmlEngDOMParser;
friend class TXmlEngNode;
friend class TXmlEngAttr;
friend class TXmlEngElement;
friend class RXmlEngDOMImplementation;
protected:
/**
* Constructor
*
* @since S60 v3.1
* @param aInternal Document pointer
*/
inline RXmlEngDocument(void* aInternal);
/**
* DISABLED for document; CloneDocumentL() must be used
*
* @since S60 v3.1
*/
inline TXmlEngNode CopyL() const;
/**
* DISABLED for document; Destroy() must be used
*
* @since S60 v3.1
*/
inline void Remove();
/**
* DISABLED for document; Destroy() must be used
*
* @since S60 v3.1
*/
inline void ReplaceWith(TXmlEngNode aNode);
private:
/**
* Main implementation of SaveL() functions that puts together all common code
* and serializes to buffer or output stream.
*
* @since S60 v3.2
* @param aNode Root node to be serialized
* @param aBuffer buffer with serialized data.
* @param aOutputStream stream that should be used during serialization
* @param aSaveOptions Options that control how serialization is performed
* @return Number of bytes written
* @leave KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding, KErrDiskFull.
*/
TInt SaveNodeL( TXmlEngNode aNode,
RBuf8& aBuffer,
MXmlEngOutputStream* aOutputStream = NULL,
TXmlEngSerializationOptions aOpt = TXmlEngSerializationOptions()) const;
/**
* "Secondary" constructor that should be called on every newly created document node.
* Initializes container for nodes owned by the document.
*
* The need for such secondary constructor is in the fact that underlying libxml2
* library knows nothing about ownership of unlinked nodes -- this feature is
* implemented in C++ DOM wrapper.
*
* @since S60 v3.1
*/
void InitOwnedNodeListL();
/**
* Adds aNode to the list of owned nodes - the nodes that are not linked yet into a
* document tree, but still destroyed with the document that owns them.
*
* @since S60 v3.1
* @param aNode Node that should be added to document
*
* In case of OOM (during growing node list container) the argument node is freed with
* xmlFreeNode()
*/
void TakeOwnership(TXmlEngNode aNode);
/**
* Remove aNode from the list of owned nodes.
*
* @since S60 v3.1
* @param aNode Node that should be removed from document
*/
void RemoveOwnership(TXmlEngNode aNode);
protected:
/** Pointer to DOM implementation object */
RXmlEngDOMImplementation* iImpl;
};// class RXmlEngDocument
#include "xmlengdocument.inl"
#endif /* XMLENGINE_DOCUMENT_H_INCLUDED */