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.

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
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.

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
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:
Copyright © Nokia Corporation 2001-2007
Back to top