1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/parser/xml/public/nsISAXXMLReader.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,207 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsIStreamListener.idl"
1.10 +
1.11 +interface nsIInputStream;
1.12 +interface nsIRequestObserver;
1.13 +interface nsIURI;
1.14 +
1.15 +interface nsISAXContentHandler;
1.16 +interface nsISAXDTDHandler;
1.17 +interface nsISAXEntityResolver;
1.18 +interface nsISAXErrorHandler;
1.19 +interface nsISAXLexicalHandler;
1.20 +interface nsIMozSAXXMLDeclarationHandler;
1.21 +
1.22 +/**
1.23 + * Interface for reading an XML document using callbacks.
1.24 + *
1.25 + * nsISAXXMLReader is the interface that an XML parser's SAX2
1.26 + * driver must implement. This interface allows an application to set
1.27 + * and query features and properties in the parser, to register event
1.28 + * handlers for document processing, and to initiate a document
1.29 + * parse.
1.30 + */
1.31 +[scriptable, uuid(5b1de802-9091-454f-9972-5753c0d0c70e)]
1.32 +interface nsISAXXMLReader : nsIStreamListener {
1.33 +
1.34 + /**
1.35 + * The base URI.
1.36 + */
1.37 + attribute nsIURI baseURI;
1.38 +
1.39 + /**
1.40 + * If the application does not register a content handler, all
1.41 + * content events reported by the SAX parser will be silently
1.42 + * ignored.
1.43 + *
1.44 + * Applications may register a new or different handler in the
1.45 + * middle of a parse, and the SAX parser must begin using the new
1.46 + * handler immediately.
1.47 + */
1.48 + attribute nsISAXContentHandler contentHandler;
1.49 +
1.50 + /**
1.51 + * If the application does not register a DTD handler, all DTD
1.52 + * events reported by the SAX parser will be silently ignored.
1.53 + *
1.54 + * Applications may register a new or different handler in the
1.55 + * middle of a parse, and the SAX parser must begin using the new
1.56 + * handler immediately.
1.57 + */
1.58 + attribute nsISAXDTDHandler dtdHandler;
1.59 +
1.60 +
1.61 + /**
1.62 + * If the application does not register an error handler, all
1.63 + * error events reported by the SAX parser will be silently ignored;
1.64 + * however, normal processing may not continue. It is highly
1.65 + * recommended that all SAX applications implement an error handler
1.66 + * to avoid unexpected bugs.
1.67 + *
1.68 + * Applications may register a new or different handler in the
1.69 + * middle of a parse, and the SAX parser must begin using the new
1.70 + * handler immediately.
1.71 + */
1.72 + attribute nsISAXErrorHandler errorHandler;
1.73 +
1.74 + /**
1.75 + * A handler for the (optional) XML declaration of a document.
1.76 + * <?xml version='1.0'?>
1.77 + *
1.78 + * @note This is not part of the SAX standard.
1.79 + */
1.80 + attribute nsIMozSAXXMLDeclarationHandler declarationHandler;
1.81 +
1.82 + /**
1.83 + * If the application does not register a lexical handler, all
1.84 + * lexical events (e.g. startDTD) reported by the SAX parser will be
1.85 + * silently ignored.
1.86 + *
1.87 + * Applications may register a new or different handler in the
1.88 + * middle of a parse, and the SAX parser must begin using the new
1.89 + * handler immediately.
1.90 + */
1.91 + attribute nsISAXLexicalHandler lexicalHandler;
1.92 +
1.93 + /**
1.94 + * Set the value of a feature flag.
1.95 + *
1.96 + * The feature name is any fully-qualified URI. It is possible
1.97 + * for an XMLReader to expose a feature value but to be unable to
1.98 + * change the current value. Some feature values may be immutable
1.99 + * or mutable only in specific contexts, such as before, during, or
1.100 + * after a parse.
1.101 + *
1.102 + * All XMLReaders are required to support setting
1.103 + * http://xml.org/sax/features/namespaces to true and
1.104 + * http://xml.org/sax/features/namespace-prefixes to false.
1.105 + *
1.106 + * @param name String flag for a parser feature.
1.107 + * @param value Turn the feature on/off.
1.108 + *
1.109 + * @note This is currently supported only for
1.110 + * http://xml.org/sax/features/namespace-prefixes . All other
1.111 + * features will result in a NOT_IMPLEMENTED exception.
1.112 + */
1.113 + void setFeature(in AString name, in boolean value);
1.114 +
1.115 + /**
1.116 + * Look up the value of a feature flag.
1.117 + *
1.118 + * The feature name is any fully-qualified URI. It is
1.119 + * possible for an XMLReader to recognize a feature name but
1.120 + * temporarily be unable to return its value.
1.121 + * Some feature values may be available only in specific
1.122 + * contexts, such as before, during, or after a parse.
1.123 + *
1.124 + * All XMLReaders are required to recognize the
1.125 + * http://xml.org/sax/features/namespaces and the
1.126 + * http://xml.org/sax/features/namespace-prefixes feature names.
1.127 + *
1.128 + * @param name String flag for a parser feature.
1.129 + *
1.130 + * @note This is currently supported only for
1.131 + * http://xml.org/sax/features/namespace-prefixes . All other
1.132 + * features will result in a NOT_IMPLEMENTED exception.
1.133 + */
1.134 + boolean getFeature(in AString name);
1.135 +
1.136 + /**
1.137 + * Set the value of a property. NOT CURRENTLY IMPLEMENTED.
1.138 + *
1.139 + * The property name is any fully-qualified URI. It is possible
1.140 + * for an XMLReader to recognize a property name but to be unable to
1.141 + * change the current value. Some property values may be immutable
1.142 + * or mutable only in specific contexts, such as before, during, or
1.143 + * after a parse.
1.144 + *
1.145 + * XMLReaders are not required to recognize setting any specific
1.146 + * property names, though a core set is defined by SAX2.
1.147 + *
1.148 + * This method is also the standard mechanism for setting
1.149 + * extended handlers.
1.150 + *
1.151 + * @param name String flag for a parser feature
1.152 + * @param value Turn the feature on/off.
1.153 + */
1.154 + void setProperty(in AString name, in nsISupports value);
1.155 +
1.156 + /**
1.157 + * Look up the value of a property. NOT CURRENTLY IMPLEMENTED.
1.158 + *
1.159 + * The property name is any fully-qualified URI. It is
1.160 + * possible for an XMLReader to recognize a property name but
1.161 + * temporarily be unable to return its value.
1.162 + * Some property values may be available only in specific
1.163 + * contexts, such as before, during, or after a parse.
1.164 + *
1.165 + * XMLReaders are not required to recognize any specific
1.166 + * property names, though an initial core set is documented for
1.167 + * SAX2.
1.168 + *
1.169 + * Implementors are free (and encouraged) to invent their own properties,
1.170 + * using names built on their own URIs.
1.171 + *
1.172 + * @param name The property name, which is a fully-qualified URI.
1.173 + * @return The current value of the property.
1.174 + */
1.175 + boolean getProperty(in AString name);
1.176 +
1.177 + /**
1.178 + *
1.179 + * @param str The UTF16 string to be parsed
1.180 + * @param contentType The content type of the string (see parseFromStream)
1.181 + *
1.182 + */
1.183 + void parseFromString(in AString str, in string contentType);
1.184 +
1.185 + /**
1.186 + *
1.187 + * @param stream The byte stream whose contents are parsed
1.188 + * @param charset The character set that was used to encode the byte
1.189 + * stream. NULL if not specified.
1.190 + * @param contentType The content type of the string - either text/xml,
1.191 + * application/xml, or application/xhtml+xml.
1.192 + * Must not be NULL.
1.193 + *
1.194 + */
1.195 + void parseFromStream(in nsIInputStream stream,
1.196 + in string charset,
1.197 + in string contentType);
1.198 +
1.199 + /**
1.200 + * Begin an asynchronous parse. This method initializes the parser,
1.201 + * and must be called before any nsIStreamListener methods. It is
1.202 + * then the caller's duty to call nsIStreamListener methods to drive
1.203 + * the parser. Once this method is called, the caller must not call
1.204 + * one of the other parse methods.
1.205 + *
1.206 + * @param observer The nsIRequestObserver to notify upon start or stop.
1.207 + * Can be NULL.
1.208 + */
1.209 + void parseAsync(in nsIRequestObserver observer);
1.210 +};
