1# ArkTS Subsystem Changelog
2
3## cl.arkts.1 Behavior Changed for xml.XmlPullParser.parse in Parsing Entity Reference Events
4
5**Access Level**
6
7Public API
8
9**Reason for Change**
10
11When parsing an XML file, the **parse** interface identifies an entity reference event as a text event, and the parsed content is integrated into the text event. Consequently, the callback function specified in **tokenValueCallbackFunction** cannot obtain the parsing result of the entity reference event.
12
13**Change Impact**
14
15This change is a non-compatible change.
16
17Before change: The XML information of an entity reference event is parsed into a text event. You cannot perform operations on the entity reference event in the callback function or determine whether the entity reference event exists based on the XML parsing result.
18
19After change: In API version 12 or version, the XML information of an entity reference event is parsed as an entity reference event. You can perform operations on the entity reference event in the callback function or determine whether the entity reference event exists based on the XML parsing result.
20
21**Start API Level**
22
23API version 12
24
25**Change Since**
26
27OpenHarmony SDK 5.0.0.38
28
29**Key API/Component Changes**
30
31xml.XmlPullParser.parse
32
33**Adaptation Guide**
34
35If the XML file does not involve entity reference events, no adaptation is required.
36
37If the XML file involves entity reference events, refer to the following example to learn the differences before and after the change. In the code snippet below, **strXml** stores the XML file to be parsed, and **func** is the callback function **tokenValueCallbackFunction**. Each event obtained upon a **parse** call triggers a callback, and the event type and XML parsing result are included in the callback.
38```
39let strXml = '<?xml version="1.0" encoding="utf-8"?>\n' +
40                '<note>&amp;happy&amp;</note>';    // The first entity reference "&amp;" is an entity reference event, and the second entity reference "&amp;", together with its following "happy", is treated as a text event.
41let textEncoder = new util.TextEncoder();
42let arrbuffer = textEncoder.encodeInto(strXml);
43let that = new xml.XmlPullParser(arrbuffer.buffer as object as ArrayBuffer, 'UTF-8');
44let str = "";
45function func(key: xml.EventType, value: xml.ParseInfo){
46  str += 'key:' + key +' value:' + value.getText() + '  ';
47  return true;
48}
49let options: xml.ParseOptions = {supportDoctype:true, ignoreNameSpace:true, tokenValueCallbackFunction:func}
50that.parse(options);
51console.log(str);
52```
53Before change:
54```
55The parsing result of &amp;happy&amp; is as follows:
56key: 4 (text event); value: &happy&
57```
58After change:
59```
60The parsing results of &amp;happy&amp; are as follows:
61key: 9 (entity reference event): value: &
62key: 4 (text event); value: happy&
63```
64
65To use an entity reference event, use API version 12 or later and strictly comply with the entity reference event format in the XML file. Do not add regular text before the entity reference to form a text event.
66
67If you do not need to use entity reference events, add regular text before the entity reference in the XML file to form a text event or write the callback function.
68
69Entity reference events:
70
71Currently, only the following entity reference events corresponding to the five predefined entities in the XML file are supported:
72
73```
74&lt;    <  less than
75&gt;    >  greater than
76&amp;   &  ampersand
77&apos;  '  apostrophe
78&quot;  "  quotation mark
79```
80In addition, if regular text exists before an entity reference, they are treated as a text event as a whole.
81
82Example:
83
84```
85<note>happy&lt;&gt;</note>: start tag event, text event, and end tag event in sequence.
86<note>&lt;&gt;happy</note>: start tag event, entity reference event, entity reference event, text event, and end tag event in sequence.
87```
88