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 "nsIStreamListener.idl"
39
40 interface nsIInputStream;
41 interface nsIRequestObserver;
42 interface nsIURI;
43
44 interface nsISAXContentHandler;
45 interface nsISAXDTDHandler;
46 interface nsISAXEntityResolver;
47 interface nsISAXErrorHandler;
48 interface nsISAXLexicalHandler;
49
50 /**
51 * Interface for reading an XML document using callbacks.
52 *
53 * nsISAXXMLReader is the interface that an XML parser's SAX2
54 * driver must implement. This interface allows an application to set
55 * and query features and properties in the parser, to register event
56 * handlers for document processing, and to initiate a document
57 * parse.
58 */
59 [scriptable, uuid(5556997e-d816-4218-8b54-803d4261206e)]
60 interface nsISAXXMLReader : nsIStreamListener {
61
62 /**
63 * The base URI.
64 */
65 attribute nsIURI baseURI;
66
67 /**
68 * If the application does not register a content handler, all
69 * content events reported by the SAX parser will be silently
70 * ignored.
71 *
72 * Applications may register a new or different handler in the
73 * middle of a parse, and the SAX parser must begin using the new
74 * handler immediately.
75 */
76 attribute nsISAXContentHandler contentHandler;
77
78 /**
79 * If the application does not register a DTD handler, all DTD
80 * events reported by the SAX parser will be silently ignored.
81 *
82 * Applications may register a new or different handler in the
83 * middle of a parse, and the SAX parser must begin using the new
84 * handler immediately.
85 */
86 attribute nsISAXDTDHandler dtdHandler;
87
88
89 /**
90 * If the application does not register an error handler, all
91 * error events reported by the SAX parser will be silently ignored;
92 * however, normal processing may not continue. It is highly
93 * recommended that all SAX applications implement an error handler
94 * to avoid unexpected bugs.
95 *
96 * Applications may register a new or different handler in the
97 * middle of a parse, and the SAX parser must begin using the new
98 * handler immediately.
99 */
100 attribute nsISAXErrorHandler errorHandler;
101
102 /**
103 * If the application does not register a lexical handler, all
104 * lexical events (e.g. startDTD) reported by the SAX parser will be
105 * silently ignored.
106 *
107 * Applications may register a new or different handler in the
108 * middle of a parse, and the SAX parser must begin using the new
109 * handler immediately.
110 */
111 attribute nsISAXLexicalHandler lexicalHandler;
112
113 /**
114 * Set the value of a feature flag. NOT CURRENTLY IMPLEMENTED.
115 *
116 * The feature name is any fully-qualified URI. It is possible
117 * for an XMLReader to expose a feature value but to be unable to
118 * change the current value. Some feature values may be immutable
119 * or mutable only in specific contexts, such as before, during, or
120 * after a parse.
121 *
122 * All XMLReaders are required to support setting
123 * http://xml.org/sax/features/namespaces to true and
124 * http://xml.org/sax/features/namespace-prefixes to false.
125 *
126 * @param name String flag for a parser feature.
127 * @param value Turn the feature on/off.
128 */
129 void setFeature(in AString name, in boolean value);
130
131 /**
132 * Look up the value of a feature flag. NOT CURRENTLY IMPLEMENTED.
133 *
134 * The feature name is any fully-qualified URI. It is
135 * possible for an XMLReader to recognize a feature name but
136 * temporarily be unable to return its value.
137 * Some feature values may be available only in specific
138 * contexts, such as before, during, or after a parse.
139 *
140 * All XMLReaders are required to recognize the
141 * http://xml.org/sax/features/namespaces and the
142 * http://xml.org/sax/features/namespace-prefixes feature names.
143 *
144 * @param name String flag for a parser feature.
145 */
146 boolean getFeature(in AString name);
147
148 /**
149 * Set the value of a property. NOT CURRENTLY IMPLEMENTED.
150 *
151 * The property name is any fully-qualified URI. It is possible
152 * for an XMLReader to recognize a property name but to be unable to
153 * change the current value. Some property values may be immutable
154 * or mutable only in specific contexts, such as before, during, or
155 * after a parse.
156 *
157 * XMLReaders are not required to recognize setting any specific
158 * property names, though a core set is defined by SAX2.
159 *
160 * This method is also the standard mechanism for setting
161 * extended handlers.
162 *
163 * @param name String flag for a parser feature
164 * @param value Turn the feature on/off.
165 */
166 void setProperty(in AString name, in nsISupports value);
167
168 /**
169 * Look up the value of a property. NOT CURRENTLY IMPLEMENTED.
170 *
171 * The property name is any fully-qualified URI. It is
172 * possible for an XMLReader to recognize a property name but
173 * temporarily be unable to return its value.
174 * Some property values may be available only in specific
175 * contexts, such as before, during, or after a parse.
176 *
177 * XMLReaders are not required to recognize any specific
178 * property names, though an initial core set is documented for
179 * SAX2.
180 *
181 * Implementors are free (and encouraged) to invent their own properties,
182 * using names built on their own URIs.
183 *
184 * @param name The property name, which is a fully-qualified URI.
185 * @return The current value of the property.
186 */
187 boolean getProperty(in AString name);
188
189 /**
190 *
191 * @param str The UTF16 string to be parsed
192 * @param contentType The content type of the string (see parseFromStream)
193 *
194 */
195 void parseFromString(in AString str, in string contentType);
196
197 /**
198 *
199 * @param stream The byte stream whose contents are parsed
200 * @param charset The character set that was used to encode the byte
201 * stream. NULL if not specified.
202 * @param contentType The content type of the string - either text/xml,
203 * application/xml, or application/xhtml+xml.
204 * Must not be NULL.
205 *
206 */
207 void parseFromStream(in nsIInputStream stream,
208 in string charset,
209 in string contentType);
210
211 /**
212 * Begin an asynchronous parse. This method initializes the parser,
213 * and must be called before any nsIStreamListener methods. It is
214 * then the caller's duty to call nsIStreamListener methods to drive
215 * the parser. Once this method is called, the caller must not call
216 * one of the other parse methods.
217 *
218 * @param observer The nsIRequestObserver to notify upon start or stop.
219 * Can be NULL.
220 */
221 void parseAsync(in nsIRequestObserver observer);
222 };