1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include
"nsIStreamListener.idl"
8 interface nsIInputStream
;
9 interface nsIRequestObserver
;
12 interface nsISAXContentHandler
;
13 interface nsISAXDTDHandler
;
14 interface nsISAXEntityResolver
;
15 interface nsISAXErrorHandler
;
16 interface nsISAXLexicalHandler
;
17 interface nsIMozSAXXMLDeclarationHandler
;
20 * Interface for reading an XML document using callbacks.
22 * nsISAXXMLReader is the interface that an XML parser's SAX2
23 * driver must implement. This interface allows an application to set
24 * and query features and properties in the parser, to register event
25 * handlers for document processing, and to initiate a document
28 [scriptable
, uuid(5b1de802
-9091-454f
-9972-5753c0d0c70e
)]
29 interface nsISAXXMLReader
: nsIStreamListener
{
34 attribute nsIURI baseURI
;
37 * If the application does not register a content handler, all
38 * content events reported by the SAX parser will be silently
41 * Applications may register a new or different handler in the
42 * middle of a parse, and the SAX parser must begin using the new
43 * handler immediately.
45 attribute nsISAXContentHandler contentHandler
;
48 * If the application does not register a DTD handler, all DTD
49 * events reported by the SAX parser will be silently ignored.
51 * Applications may register a new or different handler in the
52 * middle of a parse, and the SAX parser must begin using the new
53 * handler immediately.
55 attribute nsISAXDTDHandler dtdHandler
;
59 * If the application does not register an error handler, all
60 * error events reported by the SAX parser will be silently ignored;
61 * however, normal processing may not continue. It is highly
62 * recommended that all SAX applications implement an error handler
63 * to avoid unexpected bugs.
65 * Applications may register a new or different handler in the
66 * middle of a parse, and the SAX parser must begin using the new
67 * handler immediately.
69 attribute nsISAXErrorHandler errorHandler
;
72 * A handler for the (optional) XML declaration of a document.
73 * <?xml version='1.0'?>
75 * @note This is not part of the SAX standard.
77 attribute nsIMozSAXXMLDeclarationHandler declarationHandler
;
80 * If the application does not register a lexical handler, all
81 * lexical events (e.g. startDTD) reported by the SAX parser will be
84 * Applications may register a new or different handler in the
85 * middle of a parse, and the SAX parser must begin using the new
86 * handler immediately.
88 attribute nsISAXLexicalHandler lexicalHandler
;
91 * Set the value of a feature flag.
93 * The feature name is any fully-qualified URI. It is possible
94 * for an XMLReader to expose a feature value but to be unable to
95 * change the current value. Some feature values may be immutable
96 * or mutable only in specific contexts, such as before, during, or
99 * All XMLReaders are required to support setting
100 * http://xml.org/sax/features/namespaces to true and
101 * http://xml.org/sax/features/namespace-prefixes to false.
103 * @param name String flag for a parser feature.
104 * @param value Turn the feature on/off.
106 * @note This is currently supported only for
107 * http://xml.org/sax/features/namespace-prefixes . All other
108 * features will result in a NOT_IMPLEMENTED exception.
110 void setFeature
(in AString name
, in boolean value
);
113 * Look up the value of a feature flag.
115 * The feature name is any fully-qualified URI. It is
116 * possible for an XMLReader to recognize a feature name but
117 * temporarily be unable to return its value.
118 * Some feature values may be available only in specific
119 * contexts, such as before, during, or after a parse.
121 * All XMLReaders are required to recognize the
122 * http://xml.org/sax/features/namespaces and the
123 * http://xml.org/sax/features/namespace-prefixes feature names.
125 * @param name String flag for a parser feature.
127 * @note This is currently supported only for
128 * http://xml.org/sax/features/namespace-prefixes . All other
129 * features will result in a NOT_IMPLEMENTED exception.
131 boolean getFeature
(in AString name
);
134 * Set the value of a property. NOT CURRENTLY IMPLEMENTED.
136 * The property name is any fully-qualified URI. It is possible
137 * for an XMLReader to recognize a property name but to be unable to
138 * change the current value. Some property values may be immutable
139 * or mutable only in specific contexts, such as before, during, or
142 * XMLReaders are not required to recognize setting any specific
143 * property names, though a core set is defined by SAX2.
145 * This method is also the standard mechanism for setting
148 * @param name String flag for a parser feature
149 * @param value Turn the feature on/off.
151 void setProperty
(in AString name
, in nsISupports value
);
154 * Look up the value of a property. NOT CURRENTLY IMPLEMENTED.
156 * The property name is any fully-qualified URI. It is
157 * possible for an XMLReader to recognize a property name but
158 * temporarily be unable to return its value.
159 * Some property values may be available only in specific
160 * contexts, such as before, during, or after a parse.
162 * XMLReaders are not required to recognize any specific
163 * property names, though an initial core set is documented for
166 * Implementors are free (and encouraged) to invent their own properties,
167 * using names built on their own URIs.
169 * @param name The property name, which is a fully-qualified URI.
170 * @return The current value of the property.
172 boolean getProperty
(in AString name
);
176 * @param str The UTF16 string to be parsed
177 * @param contentType The content type of the string (see parseFromStream)
180 void parseFromString
(in AString str
, in string contentType
);
184 * @param stream The byte stream whose contents are parsed
185 * @param charset The character set that was used to encode the byte
186 * stream. NULL if not specified.
187 * @param contentType The content type of the string - either text/xml,
188 * application/xml, or application/xhtml+xml.
192 void parseFromStream
(in nsIInputStream stream
,
194 in string contentType
);
197 * Begin an asynchronous parse. This method initializes the parser,
198 * and must be called before any nsIStreamListener methods. It is
199 * then the caller's duty to call nsIStreamListener methods to drive
200 * the parser. Once this method is called, the caller must not call
201 * one of the other parse methods.
203 * @param observer The nsIRequestObserver to notify upon start or stop.
206 void parseAsync
(in nsIRequestObserver observer
);