RXmlEngDocument Class Reference

Link against: xmlengineDOM.lib

#include <xmlengdocument.h>

Inherits TXmlEngNode.

Inherited by RSenDocument.

Detailed Description

Instance of RXmlEngDocument class represents an XML document in the DOM tree.

Is a storage all nodes and information about XML data.

Dll XmlEngineDOM.lib

Since:: S60 v3.1


Public Member Functions
IMPORT_C	RXmlEngDocument ()
	Default constructor.
IMPORT_C void	OpenL (RXmlEngDOMImplementation &aDOMImpl)
	Opens the document.
IMPORT_C void	OpenL (RXmlEngDOMImplementation &aDOMImpl, void *aInternal)
	Opens the document.
IMPORT_C void	OpenL (RXmlEngDOMImplementation &aDOMImpl, TXmlEngElement aRoot)
	Opens the document.
IMPORT_C void	Close ()
	Closes document.
IMPORT_C TInt	SaveL (const TDesC &aFileName, TXmlEngNode aRoot=TXmlEngNode(), const TXmlEngSerializationOptions &aSaveOptions=TXmlEngSerializationOptions()) const
	Serializes document tree into a file.
IMPORT_C TInt	SaveL (RFs &aRFs, const TDesC &aFileName, TXmlEngNode aRoot=TXmlEngNode(), const TXmlEngSerializationOptions &aSaveOptions=TXmlEngSerializationOptions()) const
	Serializes document tree into a file.
IMPORT_C TInt	SaveL (MXmlEngOutputStream &aStream, TXmlEngNode aRoot=TXmlEngNode(), const TXmlEngSerializationOptions &aSaveOptions=TXmlEngSerializationOptions()) const
	Serializes a document tree into provided output stream, which supports progressive writing of data.
IMPORT_C TInt	SaveL (RBuf8 &aBuffer, TXmlEngNode aRoot=TXmlEngNode(), const TXmlEngSerializationOptions &aSaveOptions=TXmlEngSerializationOptions()) const
	Saves document tree into memory buffer.
IMPORT_C RXmlEngDocument	CloneDocumentL () const
	Creates complete copy of the document.
IMPORT_C TXmlEngElement	CreateDocumentElementL (const TDesC8 &aName, const TDesC8 &aNamespaceUri=KNullDesC8, const TDesC8 &aPrefix=KNullDesC8)
	Creates new element from specific namespace to be a root of the document tree.
IMPORT_C void	SetDocumentElement (TXmlEngElement aNewDocElement)
	Replaces (and destroys) document element with another one New document element is added as the last child to the document node.
IMPORT_C TPtrC8	XmlEncoding () const
	Get document encoding.
IMPORT_C TPtrC8	XmlVersion () const
	Get xml version.
IMPORT_C TPtrC8	DocumentUri () const
	Retrieves base URI (if defined) of the document or NULL.
IMPORT_C TBool	IsStandalone () const
	Check if document is standalone.
IMPORT_C void	SetXmlVersionL (const TDesC8 &aVersion)
	Sets XML version number to be shown in XML declaration when document is serialized.
IMPORT_C void	SetDocumentUriL (const TDesC8 &aUri)
	Sets location of the document.
IMPORT_C void	SetStandalone (TBool aStandalone)
	Sets 'standalone' attribute of XML declaration for a document.
IMPORT_C RXmlEngDOMImplementation	Implementation () const
	Get dom implementation.
IMPORT_C TXmlEngElement	DocumentElement () const
	Get document element.
IMPORT_C TXmlEngNode	AdoptNodeL (TXmlEngNode aSource)
	Sets "document" property on the node and all its descendants to be this RXmlEngDocument node.
IMPORT_C TXmlEngAttr	CreateAttributeL (const TDesC8 &aName, const TDesC8 &aValue=KNullDesC8)
	Creates new attribute,.
IMPORT_C TXmlEngTextNode	CreateTextNodeL (const TDesC8 &aCharacters=KNullDesC8)
	Creates new text node and copies the content string into it.
IMPORT_C TXmlEngBinaryContainer	CreateBinaryContainerL (const TDesC8 &aCid, const TDesC8 &aData)
	Creates new binary container and copies the content string into it.
IMPORT_C TXmlEngChunkContainer	CreateChunkContainerL (const TDesC8 &aCid, const RChunk &aChunk, const TInt aChunkOffset, const TInt aDataSize)
	Creates new chunk container that stores reference to memory chunk.
IMPORT_C TXmlEngFileContainer	CreateFileContainerL (const TDesC8 &aCid, const RFile &aFile)
	Creates new file container that stores reference to file in file system.
IMPORT_C TXmlEngElement	CreateElementL (const TDesC8 &aLocalName, const TDesC8 &aNamespaceUri=KNullDesC8, const TDesC8 &aPrefix=KNullDesC8)
	Creates new element node that belongs to specific namespace.
IMPORT_C TXmlEngComment	CreateCommentL (const TDesC8 &aText=KNullDesC8)
	Creates new comment node and copies the content string into it.
IMPORT_C TXmlEngCDATASection	CreateCDATASectionL (const TDesC8 &aContents=KNullDesC8)
	Creates new CDATA section node and copies the content into it.
IMPORT_C TXmlEngEntityReference	CreateEntityReferenceL (const TDesC8 &aEntityRef)
	Creates new entity reference node for aEntityName entity.
IMPORT_C TXmlEngProcessingInstruction	CreateProcessingInstructionL (const TDesC8 &aTarget, const TDesC8 &aData=KNullDesC8)
	Creates new processing instruction node and set its "target" and "data" values.
IMPORT_C void	RegisterXmlIdL (TXmlEngElement aStartElement, const TDesC8 &aLocalName, const TDesC8 &aNamespaceUri=KNullDesC8)
	Registers specified attribute as xml:id.
IMPORT_C void	RegisterXmlIdL (const TDesC8 &aLocalName, const TDesC8 &aNamespaceUri=KNullDesC8)
	Registers specified attribute as xml:id.
IMPORT_C TXmlEngElement	FindElementByXmlIdL (const TDesC8 &aValue) const
	Looks for element with specified value of xml:id.
IMPORT_C void	GetDataContainerList (RArray< TXmlEngDataContainer > &aList)
	Retrieves an array of data containers owned by this document.
Protected Member Functions
	RXmlEngDocument (void *aInternal)
	Constructor.
TXmlEngNode	CopyL () const
	DISABLED for document; CloneDocumentL() must be used.
void	Remove ()
	DISABLED for document; Destroy() must be used.
void	ReplaceWith (TXmlEngNode aNode)
	DISABLED for document; Destroy() must be used.
Protected Attributes
RXmlEngDOMImplementation *	iImpl
	Pointer to DOM implementation object.
Friends
class	RXmlEngDOMParser
class	TXmlEngNode
class	TXmlEngAttr
class	TXmlEngElement
class	RXmlEngDOMImplementation

Constructor & Destructor Documentation

IMPORT_C RXmlEngDocument::RXmlEngDocument

(

)

Default constructor.

Instance of RXmlEngDocument must be "opened" with one of OpenL() overloads.

Since:: S60 v3.1

RXmlEngDocument::RXmlEngDocument ( void * aInternal ) [inline, protected]

Constructor.

Since:: S60 v3.1

Parameters:

aInternal

Document pointer

Member Function Documentation

IMPORT_C TXmlEngNode RXmlEngDocument::AdoptNodeL

(

TXmlEngNode

aSource

)

Sets "document" property on the node and all its descendants to be this RXmlEngDocument node.

Since:: S60 v3.1

Parameters:

aSource

Node that should be added.

Returns:: Adopted node

IMPORT_C RXmlEngDocument RXmlEngDocument::CloneDocumentL

(

)

const

Creates complete copy of the document.

Since:: S60 v3.1

Returns:: Complete copy of the document tree

IMPORT_C void RXmlEngDocument::Close

(

)

Closes document.

Since:: S60 v3.1

Reimplemented in RSenDocument.

TXmlEngNode RXmlEngDocument::CopyL ( ) const [inline, protected]

DISABLED for document; CloneDocumentL() must be used.

Since:: S60 v3.1

Reimplemented from TXmlEngNode.

IMPORT_C TXmlEngAttr RXmlEngDocument::CreateAttributeL	(	const TDesC8 &	aName,
		const TDesC8 &	aValue = `KNullDesC8`
	)

Creates new attribute,.

Since:: S60 v3.1

Parameters:

	aName	Name of the atribute; no prefix allowed
	aValue	Value of the attribute (optional)

Returns:: 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 TXmlEngBinaryContainer RXmlEngDocument::CreateBinaryContainerL	(	const TDesC8 &	aCid,
		const TDesC8 &	aData
	)

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 also:: GetDataContainerList( RArray<TXmlEngDataContainer>& aList )

Since:: S60 v3.2

Parameters:

	aCid	Content identifier
	aData	Binary octets

Returns:: Created node

IMPORT_C TXmlEngCDATASection RXmlEngDocument::CreateCDATASectionL ( const TDesC8 & aContents = KNullDesC8 )

Creates new CDATA section node and copies the content into it.

Since:: S60 v3.1

Parameters:

aContents

CDATASection content

Returns:: Created node

IMPORT_C TXmlEngChunkContainer RXmlEngDocument::CreateChunkContainerL	(	const TDesC8 &	aCid,
		const RChunk &	aChunk,
		const TInt	aChunkOffset,
		const TInt	aDataSize
	)

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 also:: GetDataContainerList( RArray<TXmlEngDataContainer>& aList )

Since:: S60 v3.2

Parameters:

	aCid	Content identifier
	aChunk	RChunk reference
	aChunkOffset	Offset to the binary data in aChunk
	aDataSize	Size of binary data in aChunk

Returns:: Created node

IMPORT_C TXmlEngComment RXmlEngDocument::CreateCommentL ( const TDesC8 & aText = KNullDesC8 )

Creates new comment node and copies the content string into it.

Since:: S60 v3.1

Parameters:

aText

New comment

Returns:: Created node

IMPORT_C TXmlEngElement RXmlEngDocument::CreateDocumentElementL	(	const TDesC8 &	aName,
		const TDesC8 &	aNamespaceUri = `KNullDesC8`,
		const TDesC8 &	aPrefix = `KNullDesC8`
	)

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

Parameters:

	aName	Element name
	aNamespaceUri	Element namespace URI
	aPrefix	Element namemespace prefix

Returns:: A new root element

IMPORT_C TXmlEngElement RXmlEngDocument::CreateElementL	(	const TDesC8 &	aLocalName,
		const TDesC8 &	aNamespaceUri = `KNullDesC8`,
		const TDesC8 &	aPrefix = `KNullDesC8`
	)

Creates new element node that belongs to specific namespace.

A namespace declaration node is created on the element.

Since:: S60 v3.1

Parameters:

	aNamespaceUri	Namespace of new element
	aPrefix	Prefix to use for namespace binding and QName of the element
	aLocalName	Local name of the element

Returns:: Created node

Note:: If null namespace uri is provided element will be created without namespace.

IMPORT_C TXmlEngEntityReference RXmlEngDocument::CreateEntityReferenceL

(

const TDesC8 &

aEntityRef

)

Creates new entity reference node for aEntityName entity.

Since:: S60 v3.1

Parameters:

aEntityRef

is a string in one of the forms:

name
&name
&name; where name is the name of the entity

Returns:: Created node

Note:: < , > , ' , " and other predefined entity references should not be created with this method. These entity refs are rather "character references" and encoded/decoded automatically.

IMPORT_C TXmlEngFileContainer RXmlEngDocument::CreateFileContainerL	(	const TDesC8 &	aCid,
		const RFile &	aFile
	)

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 also:: GetDataContainerList( RArray<TXmlEngDataContainer>& aList )

Since:: S60 v3.2

Parameters:

	aCid	Content identifier
	aFile	RFile reference

Returns:: Created node

IMPORT_C TXmlEngProcessingInstruction RXmlEngDocument::CreateProcessingInstructionL	(	const TDesC8 &	aTarget,
		const TDesC8 &	aData = `KNullDesC8`
	)

Creates new processing instruction node and set its "target" and "data" values.

Since:: S60 v3.1

Parameters:

	aTarget	Target
	aData	Data

Returns:: Created node

IMPORT_C TXmlEngTextNode RXmlEngDocument::CreateTextNodeL ( const TDesC8 & aCharacters = KNullDesC8 )

Creates new text node and copies the content string into it.

Since:: S60 v3.1

Parameters:

aCharacters

Text node content

Returns:: Created node

IMPORT_C TXmlEngElement RXmlEngDocument::DocumentElement

(

)

const

Get document element.

Since:: S60 v3.1

Returns:: A document element - the top-most element in the document tree

IMPORT_C TPtrC8 RXmlEngDocument::DocumentUri

(

)

const

Retrieves base URI (if defined) of the document or NULL.

Since:: S60 v3.1

Returns:: Document URI

IMPORT_C TXmlEngElement RXmlEngDocument::FindElementByXmlIdL

(

const TDesC8 &

aValue

)

const

Looks for element with specified value of xml:id.

Since:: S60 v3.2

Parameters:

aValue

Name of attribute

Returns:: found element or null-element.

IMPORT_C void RXmlEngDocument::GetDataContainerList

(

RArray< TXmlEngDataContainer > &

aList

)

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

Parameters:

aList

Array of data containers

IMPORT_C RXmlEngDOMImplementation RXmlEngDocument::Implementation

(

)

const

Get dom implementation.

Since:: S60 v3.1

Returns:: 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 TBool RXmlEngDocument::IsStandalone

(

)

const

Check if document is standalone.

Since:: S60 v3.1

Returns:: Whether standalone="true" was specified in XML declaration in the source XML file.

IMPORT_C void RXmlEngDocument::OpenL	(	RXmlEngDOMImplementation &	aDOMImpl,
		TXmlEngElement	aRoot
	)

Opens the document.

Since:: S60 v3.2

Parameters:

	aDOMImpl	DOM implementation object
	aRoot	element taht will be root of the DOM tree

Returns:: KErrNone if succeed.

IMPORT_C void RXmlEngDocument::OpenL	(	RXmlEngDOMImplementation &	aDOMImpl,
		void *	aInternal
	)

Opens the document.

Since:: S60 v3.2

Parameters:

	aDOMImpl	DOM implementation object
	aInternal	Document pointer

Returns:: KErrNone if succeed.

IMPORT_C void RXmlEngDocument::OpenL

(

RXmlEngDOMImplementation &

aDOMImpl

)

Opens the document.

Since:: S60 v3.2

Parameters:

aDOMImpl

DOM implementation object

Returns:: KErrNone if succeed.

IMPORT_C void RXmlEngDocument::RegisterXmlIdL	(	const TDesC8 &	aLocalName,
		const TDesC8 &	aNamespaceUri = `KNullDesC8`
	)

Registers specified attribute as xml:id.

Not to search whole tree see

See also:: RegisterXmlId(TXmlEngElement,const TDesC8,const TDesC8)

Since:: S60 v3.2

Parameters:

	aLocalName	Name of attribute
	aNamespaceUri	Namespace of new element (default empty)

IMPORT_C void RXmlEngDocument::RegisterXmlIdL	(	TXmlEngElement	aStartElement,
		const TDesC8 &	aLocalName,
		const TDesC8 &	aNamespaceUri = `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 also:: RegisterXmlId(const TDesC8,const TDesC8)

Since:: S60 v3.2

Parameters:

	aStartElement	Root of tree to search (should be part of the document)
	aLocalName	Name of attribute
	aNamespaceUri	Namespace of new element (default empty)

void RXmlEngDocument::Remove ( ) [inline, protected]

DISABLED for document; Destroy() must be used.

Since:: S60 v3.1

Reimplemented from TXmlEngNode.

void RXmlEngDocument::ReplaceWith ( TXmlEngNode aNode ) [inline, protected]

DISABLED for document; Destroy() must be used.

Since:: S60 v3.1

Reimplemented from TXmlEngNode.

IMPORT_C TInt RXmlEngDocument::SaveL	(	RBuf8 &	aBuffer,
		TXmlEngNode	aRoot = `TXmlEngNode()`,
		const TXmlEngSerializationOptions &	aSaveOptions = `TXmlEngSerializationOptions()`
	)	const

Saves document tree into memory buffer.

Since:: S60 v3.1

Parameters:

	aBuffer	Resulting buffer
	aRoot	A "root" of the subtree to serialize
	aSaveOptions	Various options to be effective during serialization

Returns:: 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 also:: TXmlEngSerializationOptions

IMPORT_C TInt RXmlEngDocument::SaveL	(	MXmlEngOutputStream &	aStream,
		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

Parameters:

	aStream	An output stream to write serialized DOM tree
	aRoot	Root node to be serialized
	aSaveOptions	Options that control how serialization is performed

Returns:: Number of byte written

Leave:: KXmlEngErrWrongUseOfAPI or one of general codes (e.g.KErrNoMemory)

See also:: MXmlEngOutputStream

IMPORT_C TInt RXmlEngDocument::SaveL	(	RFs &	aRFs,
		const TDesC &	aFileName,
		TXmlEngNode	aRoot = `TXmlEngNode()`,
		const TXmlEngSerializationOptions &	aSaveOptions = `TXmlEngSerializationOptions()`
	)	const

Serializes document tree into a file.

Since:: S60 v3.2

Parameters:

	aRFs	File Server session
	aFileName	A file name (with path)
	aRoot	Root node to be serialized
	aSaveOptions	Options that control how serialization is performed

Returns:: Number of byte written

Leave:: KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding, KErrDiskFull.

IMPORT_C TInt RXmlEngDocument::SaveL	(	const TDesC &	aFileName,
		TXmlEngNode	aRoot = `TXmlEngNode()`,
		const TXmlEngSerializationOptions &	aSaveOptions = `TXmlEngSerializationOptions()`
	)	const

Serializes document tree into a file.

Since:: S60 v3.2

Parameters:

	aFileName	A file name (with path)
	aRoot	Root node to be serialized
	aSaveOptions	Options that control how serialization is performed

Returns:: Number of byte written

Leave:: KErrNoMemory, KErrGeneral, KXmlEngErrWrongEncoding, KErrDiskFull.

IMPORT_C void RXmlEngDocument::SetDocumentElement

(

TXmlEngElement

aNewDocElement

)

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

Parameters:

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 also:: TXmlEngElement::ReconcileNamespacesL()

IMPORT_C void RXmlEngDocument::SetDocumentUriL

(

const TDesC8 &

aUri

)

Sets location of the document.

Document's URI is used as top-level base URI definition.

Since:: S60 v3.1

Parameters:

aUri

New document URI

IMPORT_C void RXmlEngDocument::SetStandalone

(

TBool

aStandalone

)

Sets 'standalone' attribute of XML declaration for a document.

Since:: S60 v3.1

Parameters:

aStandalone

Is document standalone

IMPORT_C void RXmlEngDocument::SetXmlVersionL

(

const TDesC8 &

aVersion

)

Sets XML version number to be shown in XML declaration when document is serialized.

Since:: S60 v3.1

Parameters:

aVersion

New version

IMPORT_C TPtrC8 RXmlEngDocument::XmlEncoding

(

)

const

Get document encoding.

Since:: S60 v3.1

Returns:: Encoding of the source XML data.

IMPORT_C TPtrC8 RXmlEngDocument::XmlVersion

(

)

const

Get xml version.

Since:: S60 v3.1

Returns:: Version number of XML taken from XML declaration

Friends And Related Function Documentation

friend class RXmlEngDOMImplementation [friend]

friend class RXmlEngDOMParser [friend]

friend class TXmlEngAttr [friend]

friend class TXmlEngElement [friend]

friend class TXmlEngNode [friend]

Field Documentation

RXmlEngDOMImplementation* RXmlEngDocument::iImpl [protected]

Pointer to DOM implementation object.

The documentation for this class was generated from the following files:

RXmlEngDocument Class Reference

Detailed Description

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Field Documentation