1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* ***** BEGIN LICENSE BLOCK *****
3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 *
5 * The contents of this file are subject to the Mozilla Public License Version
6 * 1.1 (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 * http://www.mozilla.org/MPL/
9 *
10 * Software distributed under the License is distributed on an "AS IS" basis,
11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 * for the specific language governing rights and limitations under the
13 * License.
14 *
15 * The Original Code is mozilla.org code.
16 *
17 * The Initial Developer of the Original Code is Robert Sayre.
18 *
19 * Portions created by the Initial Developer are Copyright (C) 2005
20 * the Initial Developer. All Rights Reserved.
21 *
22 * Contributor(s):
23 *
24 * Alternatively, the contents of this file may be used under the terms of
25 * either the GNU General Public License Version 2 or later (the "GPL"), or
26 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
27 * in which case the provisions of the GPL or the LGPL are applicable instead
28 * of those above. If you wish to allow use of your version of this file only
29 * under the terms of either the GPL or the LGPL, and not to allow others to
30 * use your version of this file under the terms of the MPL, indicate your
31 * decision by deleting the provisions above and replace them with the notice
32 * and other provisions required by the GPL or the LGPL. If you do not delete
33 * the provisions above, a recipient may use your version of this file under
34 * the terms of any one of the MPL, the GPL or the LGPL.
35 *
36 * ***** END LICENSE BLOCK ***** */
37
38 #include "nsISupports.idl"
39
40 interface nsISAXAttributes;
41
42 /**
43 * Receive notification of the logical content of a document.
44 *
45 * This is the main interface that most SAX applications implement: if
46 * the application needs to be informed of basic parsing events, it
47 * implements this interface and registers an instance with the SAX
48 * parser. The parser uses the instance to report basic
49 * document-related events like the start and end of elements and
50 * character data.
51 *
52 * The order of events in this interface is very important, and
53 * mirrors the order of information in the document itself. For
54 * example, all of an element's content (character data, processing
55 * instructions, and/or subelements) will appear, in order, between
56 * the startElement event and the corresponding endElement event.
57 */
58 [scriptable, uuid(2a99c757-dfee-4806-bff3-f721440412e0)]
59 interface nsISAXContentHandler : nsISupports
60 {
61 /**
62 * Receive notification of the beginning of a document.
63 *
64 * The SAX parser will invoke this method only once, before any
65 * other event callbacks.
66 */
67 void startDocument();
68
69 /**
70 * Receive notification of the end of a document.
71 *
72 * There is an apparent contradiction between the documentation for
73 * this method and the documentation for ErrorHandler.fatalError().
74 * Until this ambiguity is resolved in a future major release,
75 * clients should make no assumptions about whether endDocument()
76 * will or will not be invoked when the parser has reported a
77 * fatalError() or thrown an exception.
78 *
79 * The SAX parser will invoke this method only once, and it will be
80 * the last method invoked during the parse. The parser shall not
81 * invoke this method until it has either abandoned parsing (because
82 * of an unrecoverable error) or reached the end of input.
83 */
84 void endDocument();
85
86 /**
87 * Receive notification of the beginning of an element.
88 *
89 * The Parser will invoke this method at the beginning of every
90 * element in the XML document; there will be a corresponding
91 * endElement event for every startElement event (even when the
92 * element is empty). All of the element's content will be reported,
93 * in order, before the corresponding endElement event.
94 *
95 * This event allows up to three name components for each element:
96 *
97 * 1.) the Namespace URI;
98 * 2.) the local name; and
99 * 3.) the qualified (prefixed) name.
100 *
101 * Any or all of these may be provided, depending on the values of
102 * the http://xml.org/sax/features/namespaces and the
103 * http://xml.org/sax/features/namespace-prefixes properties:
104 *
105 * The Namespace URI and local name are required when the namespaces
106 * property is true (the default), and are optional when the
107 * namespaces property is false (if one is specified, both must be);
108 *
109 * The qualified name is required when the namespace-prefixes
110 * property is true, and is optional when the namespace-prefixes
111 * property is false (the default).
112 *
113 * Note that the attribute list provided will contain only
114 * attributes with explicit values (specified or defaulted):
115 * #IMPLIED attributes will be omitted. The attribute list will
116 * contain attributes used for Namespace declarations (xmlns*
117 * attributes) only if the
118 * http://xml.org/sax/features/namespace-prefixes property is true
119 * (it is false by default, and support for a true value is
120 * optional).
121 *
122 * @param uri the Namespace URI, or the empty string if the
123 * element has no Namespace URI or if Namespace
124 * processing is not being performed
125 * @param localName the local name (without prefix), or the
126 * empty string if Namespace processing is not being
127 * performed
128 * @param qName the qualified name (with prefix), or the
129 * empty string if qualified names are not available
130 * @param atts the attributes attached to the element. If
131 * there are no attributes, it shall be an empty
132 * SAXAttributes object. The value of this object after
133 * startElement returns is undefined
134 */
135 void startElement(in AString uri, in AString localName,
136 in AString qName, in nsISAXAttributes attributes);
137
138 /**
139 * Receive notification of the end of an element.
140 *
141 * The SAX parser will invoke this method at the end of every
142 * element in the XML document; there will be a corresponding
143 * startElement event for every endElement event (even when the
144 * element is empty).
145 *
146 * For information on the names, see startElement.
147 *
148 * @param uri the Namespace URI, or the empty string if the
149 * element has no Namespace URI or if Namespace
150 * processing is not being performed
151 * @param localName the local name (without prefix), or the
152 * empty string if Namespace processing is not being
153 * performed
154 * @param qName the qualified XML name (with prefix), or the
155 * empty string if qualified names are not available
156 */
157 void endElement(in AString uri, in AString localName, in AString qName);
158
159 /**
160 * Receive notification of character data.
161 *
162 * The Parser will call this method to report each chunk of
163 * character data. SAX parsers may return all contiguous character
164 * data in a single chunk, or they may split it into several chunks;
165 * however, all of the characters in any single event must come from
166 * the same external entity so that the Locator provides useful
167 * information.
168 *
169 * Note that some parsers will report whitespace in element
170 * content using the ignorableWhitespace method rather than this one
171 * (validating parsers must do so).
172 *
173 * @param value the characters from the XML document
174 */
175 void characters(in AString value);
176
177 /**
178 * Receive notification of a processing instruction.
179 *
180 * The Parser will invoke this method once for each processing
181 * instruction found: note that processing instructions may occur
182 * before or after the main document element.
183 *
184 * A SAX parser must never report an XML declaration (XML 1.0,
185 * section 2.8) or a text declaration (XML 1.0, section 4.3.1) using
186 * this method.
187 *
188 * @param target the processing instruction target
189 * @param data the processing instruction data, or null if
190 * none was supplied. The data does not include any
191 * whitespace separating it from the target
192 */
193 void processingInstruction(in AString target, in AString data);
194
195 /**
196 * Receive notification of ignorable whitespace in element content.
197 *
198 * Validating Parsers must use this method to report each chunk of
199 * whitespace in element content (see the W3C XML 1.0
200 * recommendation, section 2.10): non-validating parsers may also
201 * use this method if they are capable of parsing and using content
202 * models.
203 *
204 * SAX parsers may return all contiguous whitespace in a single
205 * chunk, or they may split it into several chunks; however, all of
206 * the characters in any single event must come from the same
207 * external entity, so that the Locator provides useful information.
208 *
209 * @param whitespace the characters from the XML document
210 */
211 void ignorableWhitespace(in AString whitespace);
212
213 /**
214 * Begin the scope of a prefix-URI Namespace mapping.
215 *
216 * The information from this event is not necessary for normal
217 * Namespace processing: the SAX XML reader will automatically
218 * replace prefixes for element and attribute names when the
219 * http://xml.org/sax/features/namespaces feature is
220 * true (the default).
221 *
222 * There are cases, however, when applications need to use prefixes
223 * in character data or in attribute values, where they cannot
224 * safely be expanded automatically; the start/endPrefixMapping
225 * event supplies the information to the application to expand
226 * prefixes in those contexts itself, if necessary.
227 *
228 * Note that start/endPrefixMapping events are not guaranteed to be
229 * properly nested relative to each other: all startPrefixMapping
230 * events will occur immediately before the corresponding
231 * startElement event, and all endPrefixMapping events will occur
232 * immediately after the corresponding endElement event, but their
233 * order is not otherwise guaranteed.
234 *
235 * There should never be start/endPrefixMapping events for the
236 * "xml" prefix, since it is predeclared and immutable.
237 *
238 * @param prefix The Namespace prefix being declared. An empty
239 * string is used for the default element namespace,
240 * which has no prefix.
241 * @param uri The Namespace URI the prefix is mapped to.
242 */
243 void startPrefixMapping(in AString prefix, in AString uri);
244
245 /**
246 * End the scope of a prefix-URI mapping.
247 *
248 * See startPrefixMapping for details. These events will always
249 * occur immediately after the corresponding endElement event, but
250 * the order of endPrefixMapping events is not otherwise guaranteed.
251 *
252 * @param prefix The prefix that was being mapped. This is the empty
253 * string when a default mapping scope ends.
254 */
255 void endPrefixMapping(in AString prefix);
256 //XXX documentLocator
257 };