|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE task |
|
11 PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> |
|
12 <task id="GUID-E20C2C98-A294-551B-99CF-BE1DAA6F597E" xml:lang="en"><title>Serialising |
|
13 XML DOM</title><shortdesc>This topic explains how to serialise a DOM document and save it |
|
14 to a file. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody> |
|
15 <prereq><p>Before you start, you must: </p> <ul> |
|
16 <li id="GUID-128FA93B-B492-5F86-8E94-2DE1FDC3E29C"><p>understand the concepts |
|
17 of <xref href="http://www.w3.org/DOM/" scope="external">Document Object Model |
|
18 (DOM)</xref> and serialisation </p> </li> |
|
19 <li id="GUID-B55CE275-DE00-5788-8D53-0F581078FFC9"><p>understand the structure |
|
20 and classes of the <xref href="GUID-5ACFA8E4-3C4B-5851-A43E-9FA72D0B8403.dita">XML |
|
21 DOM Engine </xref> component </p> </li> |
|
22 <li id="GUID-75078E65-3FB2-5DC1-8D52-3D5B0E1A9674"><p>have created an <xref href="GUID-5748D958-9480-3358-A399-6B92293B86D9.dita"><apiname>RXmlEngDocument</apiname></xref> (called <codeph>myDoc </codeph> in |
|
23 this example), either by parsing an XML file (as indicated in the <xref href="GUID-C5C30218-311C-58D9-A990-3F95642F7517.dita">XML |
|
24 DOM Parsing Tutorial</xref>) or by adding nodes to a new DOM tree. </p> </li> |
|
25 </ul> </prereq> |
|
26 <context> <p>The XML Engine is based on the libxml2 library, which supports |
|
27 the serialisation of XML documents. This process converts a DOM tree into |
|
28 a format that can be saved to a file or transferred through a network connection. </p> <p>This |
|
29 tutorial explains how to save an existing XML document to a file. To store |
|
30 the result in a buffer, use the <xref href="GUID-5748D958-9480-3358-A399-6B92293B86D9.dita"><apiname>SetOutput(RBuf8&)</apiname></xref> method |
|
31 instead of the <xref href="GUID-5748D958-9480-3358-A399-6B92293B86D9.dita"><apiname>SetOutputL(TDesC&)</apiname></xref> method |
|
32 used below. </p> </context> |
|
33 <steps id="GUID-818D2E7F-4ECB-5687-AF68-2C02930519C7"> |
|
34 <step id="GUID-A241AD29-F46C-51DE-A30A-7F37AAACB5D4"><cmd/> |
|
35 <info>If you have not done it earlier, call the <xref href="GUID-5748D958-9480-3358-A399-6B92293B86D9.dita"><apiname>XmlEnginePushL()</apiname></xref> method |
|
36 to open the XML library and put serialisation resources on the clean-up stack. </info> |
|
37 <stepxmp><codeblock id="GUID-8CBCDA21-7DFB-5608-811F-4F9B126BD0A7" xml:space="preserve">XmlEnginePushL();</codeblock> </stepxmp> |
|
38 </step> |
|
39 <step id="GUID-3A35C368-F1CB-5183-8C4D-1E141F2B8ED4"><cmd>Create an instance |
|
40 of the serialiser by calling its <xref href="GUID-5748D958-9480-3358-A399-6B92293B86D9.dita"><apiname>NewL()</apiname></xref> method. </cmd> |
|
41 <info>The serialiser type is a member of the <xref href="GUID-5748D958-9480-3358-A399-6B92293B86D9.dita"><apiname>TXmlEngSerializerType</apiname></xref> enumeration. </info> |
|
42 <stepxmp><codeblock id="GUID-587BB00E-579E-593F-B6CD-F58A548C2FBE" xml:space="preserve">CXmlEngSerializer* serializer = CXmlEngSerializer::NewL( ESerializerDefault );</codeblock> </stepxmp> |
|
43 </step> |
|
44 <step id="GUID-79270763-1081-57D8-9EB2-D21F7DF7035F"><cmd>Configure the serialiser |
|
45 by using the <xref href="GUID-5748D958-9480-3358-A399-6B92293B86D9.dita"><apiname>SetOutputL()</apiname></xref> and <xref href="GUID-5748D958-9480-3358-A399-6B92293B86D9.dita"><apiname>SetSerialisationOptions()</apiname></xref> methods. </cmd> |
|
46 <info>You set the type of output (file, buffer, or stream) by choosing one |
|
47 of the <codeph>SetOutput()</codeph> or <codeph>SetOuputL()</codeph> methods. </info> |
|
48 <stepxmp><codeblock id="GUID-5CCEBBCE-EE31-56B5-ADB7-06362097A90E" xml:space="preserve">_LIT( KOutputFile, "c:\\tutorial.xml" ); |
|
49 serializer->SetOutputL( KOutputFile );</codeblock> </stepxmp> |
|
50 <info>The <codeph>SetSerialisationOptions()</codeph> function sets other serialisation |
|
51 options from the <xref href="GUID-5748D958-9480-3358-A399-6B92293B86D9.dita"><apiname>TXmlEngSerializationOptions</apiname></xref> class. </info> |
|
52 <stepxmp><codeblock id="GUID-DF615E82-757C-518F-BDC7-55189153D4D7" xml:space="preserve">TXmlEngSerializationOptions options( TXmlEngSerializationOptions::KOptionIndent ); |
|
53 serializer->SetSerializationOptions( options ); |
|
54 </codeblock> </stepxmp> |
|
55 </step> |
|
56 <step id="GUID-77071B6A-3FAE-5BC6-BC91-FF998AC1E744"><cmd/> |
|
57 <info>Call the <xref href="GUID-5748D958-9480-3358-A399-6B92293B86D9.dita"><apiname>SerializeL()</apiname></xref> method to save |
|
58 your document to the <filepath>tutorial.xml</filepath> file. </info> |
|
59 <stepxmp><codeblock id="GUID-2358B434-3A2C-5EEE-A45D-1F0446CBC47F" xml:space="preserve">TInt bytesWritten = serializer->SerializeL( myDoc );</codeblock> </stepxmp> |
|
60 </step> |
|
61 <step id="GUID-EC0F4C51-CD58-5142-A17D-EB4FCAAA7099"><cmd/> |
|
62 <info>Free your resources as necessary. </info> |
|
63 <substeps id="GUID-17893DB6-AFBE-5E69-8FBD-F4010C7B0664"> |
|
64 <substep id="GUID-6475F251-42DE-51B2-A4DD-26195B95ACB2"><cmd/> |
|
65 <info>Close the XML library by calling the <xref href="GUID-5748D958-9480-3358-A399-6B92293B86D9.dita"><apiname>XmlPopAndClose()</apiname></xref> method. |
|
66 This method also removes the serialisation resources from the clean-up stack. </info> |
|
67 </substep> |
|
68 <substep id="GUID-3B286D3D-049D-52A2-893A-B5601A79C727"><cmd/> |
|
69 <info>Perform any other clean-up operations. </info> |
|
70 </substep> |
|
71 </substeps> |
|
72 </step> |
|
73 </steps> |
|
74 <result><p>The data in the <codeph>myDoc</codeph> XML document |
|
75 is stored in the <filepath>tutorial.xml</filepath> file. </p> </result> |
|
76 </taskbody></task> |