• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1/*
2 * Copyright (c) 2021 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * The xml module provides utilities for converting XML text to Javascript object, XML generation and parsing.
18 * @since 8
19 * @syscap SystemCapability.Utils.Lang
20 * @permission N/A
21 */
22declare namespace xml {
23
24    /**
25     * The XmlSerializer interface is used to generate an xml file.
26     * @name XmlSerializer
27     * @since 8
28     * @syscap SystemCapability.Utils.Lang
29     */
30    class XmlSerializer {
31        /**
32         * A parameterized constructor used to create a new XmlSerializer instance.
33         * As the input parameter of the constructor function, init supports three types.
34         * The input parameter is an Arrarybuffer.
35         * The input parameter is a DataView.
36         * The input parameter is an encoding format of string type.
37         * @throws {BusinessError} 401 - if the input parameters are invalid.
38         */
39        constructor(buffer: ArrayBuffer | DataView, encoding?: string);
40
41        /**
42         * Write an attribute.
43         * @since 8
44         * @syscap SystemCapability.Utils.Lang
45         * @param name Key name of the attribute.
46         * @param value Values of attribute.
47         * @throws {BusinessError} 401 - if the input parameters are invalid.
48         */
49        setAttributes(name: string, value: string): void;
50
51        /**
52         * Add an empty element.
53         * @since 8
54         * @syscap SystemCapability.Utils.Lang
55         * @param name Key name of the attribute.
56         * @param value Values of element.
57         * @throws {BusinessError} 401 - The type of name must be string.
58         */
59        addEmptyElement(name: string): void;
60
61        /**
62         * Writes xml declaration with encoding. For example: <?xml version="1.0" encoding="utf-8"?>.
63         * @since 8
64         * @syscap SystemCapability.Utils.Lang
65         */
66        setDeclaration(): void;
67
68        /**
69         * Writes a element start tag with the given name.
70         * @since 8
71         * @syscap SystemCapability.Utils.Lang
72         * @param name Name of the element.
73         * @throws {BusinessError} 401 - The type of name must be string.
74         */
75        startElement(name: string): void;
76
77        /**
78         * Writes end tag of the element.
79         * @since 8
80         * @syscap SystemCapability.Utils.Lang
81         */
82        endElement(): void;
83
84        /**
85         * Writes the namespace of the current element tag.
86         * @since 8
87         * @syscap SystemCapability.Utils.Lang
88         * @param prefix Values name of the prefix.
89         * @param namespace Values of namespace.
90         * @throws {BusinessError} 401 - if the input parameters are invalid.
91         */
92        setNamespace(prefix: string, namespace: string): void;
93
94        /**
95         * Writes the comment.
96         * @since 8
97         * @syscap SystemCapability.Utils.Lang
98         * @param text Values of comment.
99         * @throws {BusinessError} 401 - The type of text must be string.
100         */
101        setComment(text: string): void;
102
103        /**
104         * Writes the CDATA.
105         * @since 8
106         * @syscap SystemCapability.Utils.Lang
107         * @param text Values of CDATA.
108         * @throws {BusinessError} 401 - The type of text must be string.
109         */
110        setCDATA(text: string): void;
111
112        /**
113         * Writes the text.
114         * @since 8
115         * @syscap SystemCapability.Utils.Lang
116         * @param text Values of text.
117         * @throws {BusinessError} 401 - The type of text must be string.
118         */
119        setText(text: string): void;
120
121        /**
122         * Writes the DOCTYPE.
123         * @since 8
124         * @syscap SystemCapability.Utils.Lang
125         * @param text Values of docType.
126         * @throws {BusinessError} 401 - The type of text must be string.
127         */
128        setDocType(text: string): void;
129    }
130
131    enum EventType {
132        /**
133          * Start a document.
134          * @since 8
135          * @syscap SystemCapability.Utils.Lang
136          */
137        START_DOCUMENT,
138        /**
139          * End a document.
140          * @since 8
141          * @syscap SystemCapability.Utils.Lang
142          */
143        END_DOCUMENT,
144        /**
145          * Start a tag.
146          * @since 8
147          * @syscap SystemCapability.Utils.Lang
148          */
149        START_TAG,
150        /**
151          * End a tag.
152          * @since 8
153          * @syscap SystemCapability.Utils.Lang
154          */
155        END_TAG,
156        /**
157          * Character data.
158          * @since 8
159          * @syscap SystemCapability.Utils.Lang
160          */
161        TEXT,
162        /**
163          * A CDATA sections.
164          * @since 8
165          * @syscap SystemCapability.Utils.Lang
166          */
167        CDSECT,
168        /**
169          * An XML comment.
170          * @since 8
171          * @syscap SystemCapability.Utils.Lang
172          */
173        COMMENT,
174        /**
175          * An XML document type declaration.
176          * @since 8
177          * @syscap SystemCapability.Utils.Lang
178          */
179        DOCDECL,
180        /**
181          * An XML processing instruction declaration.
182          * @since 8
183          * @syscap SystemCapability.Utils.Lang
184          */
185        INSTRUCTION,
186        /**
187          * An entity reference.
188          * @since 8
189          * @syscap SystemCapability.Utils.Lang
190          */
191        ENTITY_REFERENCE,
192        /**
193          * A whitespace.
194          * @since 8
195          * @syscap SystemCapability.Utils.Lang
196          */
197        WHITESPACE
198    }
199
200    /** The current parse info.  */
201    interface ParseInfo {
202        /**
203          * The current column number, starting from 1.
204          * @since 8
205          * @syscap SystemCapability.Utils.Lang
206          */
207        getColumnNumber(): number;
208        /**
209          * The current depth of the element.
210          * @since 8
211          * @syscap SystemCapability.Utils.Lang
212          */
213        getDepth(): number;
214        /**
215          * The current line number, starting from 1.
216          * @since 8
217          * @syscap SystemCapability.Utils.Lang
218          */
219        getLineNumber(): number;
220        /**
221          * The current element's name.
222          * @since 8
223          * @syscap SystemCapability.Utils.Lang
224          */
225        getName(): string;
226        /**
227          * The current element's namespace.
228          * @since 8
229          * @syscap SystemCapability.Utils.Lang
230          */
231        getNamespace(): string;
232        /**
233          * The current element's prefix.
234          * @since 8
235          * @syscap SystemCapability.Utils.Lang
236          */
237        getPrefix(): string;
238        /**
239          * The text content of the current event as String.
240          * @since 8
241          * @syscap SystemCapability.Utils.Lang
242          */
243        getText(): string;
244        /**
245          * Returns true if the current element is empty.
246          * @since 8
247          * @syscap SystemCapability.Utils.Lang
248          */
249        isEmptyElementTag(): boolean;
250        /**
251          * Checks whether the current TEXT event contains only whitespace characters.
252          * @since 8
253          * @syscap SystemCapability.Utils.Lang
254          */
255        isWhitespace(): boolean;
256        /**
257          * Returns the number of attributes of the current start tag.
258          * @since 8
259          * @syscap SystemCapability.Utils.Lang
260          */
261        getAttributeCount(): number;
262    }
263
264    /** Parse options for XmlPullParser. */
265    interface ParseOptions {
266
267        /**
268         * Whether to parsing Doctype of the elements.
269         * @since 8
270         * @syscap SystemCapability.Utils.Lang
271         */
272        supportDoctype?: boolean;
273
274        /**
275         * Whether to ignore parsing texts of the elements.
276         * @since 8
277         * @syscap SystemCapability.Utils.Lang
278         */
279        ignoreNameSpace?: boolean;
280
281        /**
282         * Tag value callback function.
283         * @since 8
284         * @syscap SystemCapability.Utils.Lang
285         * @param name The current tag name.
286         * @param value The current tag value.
287         * @returns Returns a Boolean variable for whether parse continually.
288         */
289        tagValueCallbackFunction?: (name: string, value: string) => boolean;
290
291        /**
292         * Attribute value callback function.
293         * @since 8
294         * @syscap SystemCapability.Utils.Lang
295         * @param name The current attribute name.
296         * @param value The current attribute value.
297         * @returns Returns a Boolean variable for whether parse continually.
298         */
299        attributeValueCallbackFunction?: (name: string, value: string) => boolean;
300
301        /**
302         * Token value callback function.
303         * @since 8
304         * @syscap SystemCapability.Utils.Lang
305         * @param eventType The current token eventtype.
306         * @param value The current token parseinfo.
307         * @returns Returns a Boolean variable for whether parse continually.
308         */
309        tokenValueCallbackFunction?: (eventType: EventType, value: ParseInfo) => boolean;
310    }
311
312    /**
313     * The XmlPullParser interface is used to parse the existing xml file.
314     * @name XmlPullParser
315     * @since 8
316     * @syscap SystemCapability.Utils.Lang
317     */
318    class XmlPullParser {
319        /**
320         * A constructor used to create a new XmlPullParser instance.
321         * @throws {BusinessError} 401 - if the input parameters are invalid.
322         */
323        constructor(buffer: ArrayBuffer | DataView, encoding?: string);
324
325        /**
326         * Starts parsing the XML file.
327         * @since 8
328         * @syscap SystemCapability.Utils.Lang
329         * @param option parse options for XmlPullParser, the interface including two Boolean variables and three callback functions.
330         * @throws {BusinessError} 401 - The type of option must be ParseOptions.
331         */
332        parse(option: ParseOptions): void;
333    }
334}
335export default xml;