michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "nsIStreamListener.idl" michael@0: michael@0: interface nsIInputStream; michael@0: interface nsIRequestObserver; michael@0: interface nsIURI; michael@0: michael@0: interface nsISAXContentHandler; michael@0: interface nsISAXDTDHandler; michael@0: interface nsISAXEntityResolver; michael@0: interface nsISAXErrorHandler; michael@0: interface nsISAXLexicalHandler; michael@0: interface nsIMozSAXXMLDeclarationHandler; michael@0: michael@0: /** michael@0: * Interface for reading an XML document using callbacks. michael@0: * michael@0: * nsISAXXMLReader is the interface that an XML parser's SAX2 michael@0: * driver must implement. This interface allows an application to set michael@0: * and query features and properties in the parser, to register event michael@0: * handlers for document processing, and to initiate a document michael@0: * parse. michael@0: */ michael@0: [scriptable, uuid(5b1de802-9091-454f-9972-5753c0d0c70e)] michael@0: interface nsISAXXMLReader : nsIStreamListener { michael@0: michael@0: /** michael@0: * The base URI. michael@0: */ michael@0: attribute nsIURI baseURI; michael@0: michael@0: /** michael@0: * If the application does not register a content handler, all michael@0: * content events reported by the SAX parser will be silently michael@0: * ignored. michael@0: * michael@0: * Applications may register a new or different handler in the michael@0: * middle of a parse, and the SAX parser must begin using the new michael@0: * handler immediately. michael@0: */ michael@0: attribute nsISAXContentHandler contentHandler; michael@0: michael@0: /** michael@0: * If the application does not register a DTD handler, all DTD michael@0: * events reported by the SAX parser will be silently ignored. michael@0: * michael@0: * Applications may register a new or different handler in the michael@0: * middle of a parse, and the SAX parser must begin using the new michael@0: * handler immediately. michael@0: */ michael@0: attribute nsISAXDTDHandler dtdHandler; michael@0: michael@0: michael@0: /** michael@0: * If the application does not register an error handler, all michael@0: * error events reported by the SAX parser will be silently ignored; michael@0: * however, normal processing may not continue. It is highly michael@0: * recommended that all SAX applications implement an error handler michael@0: * to avoid unexpected bugs. michael@0: * michael@0: * Applications may register a new or different handler in the michael@0: * middle of a parse, and the SAX parser must begin using the new michael@0: * handler immediately. michael@0: */ michael@0: attribute nsISAXErrorHandler errorHandler; michael@0: michael@0: /** michael@0: * A handler for the (optional) XML declaration of a document. michael@0: * michael@0: * michael@0: * @note This is not part of the SAX standard. michael@0: */ michael@0: attribute nsIMozSAXXMLDeclarationHandler declarationHandler; michael@0: michael@0: /** michael@0: * If the application does not register a lexical handler, all michael@0: * lexical events (e.g. startDTD) reported by the SAX parser will be michael@0: * silently ignored. michael@0: * michael@0: * Applications may register a new or different handler in the michael@0: * middle of a parse, and the SAX parser must begin using the new michael@0: * handler immediately. michael@0: */ michael@0: attribute nsISAXLexicalHandler lexicalHandler; michael@0: michael@0: /** michael@0: * Set the value of a feature flag. michael@0: * michael@0: * The feature name is any fully-qualified URI. It is possible michael@0: * for an XMLReader to expose a feature value but to be unable to michael@0: * change the current value. Some feature values may be immutable michael@0: * or mutable only in specific contexts, such as before, during, or michael@0: * after a parse. michael@0: * michael@0: * All XMLReaders are required to support setting michael@0: * http://xml.org/sax/features/namespaces to true and michael@0: * http://xml.org/sax/features/namespace-prefixes to false. michael@0: * michael@0: * @param name String flag for a parser feature. michael@0: * @param value Turn the feature on/off. michael@0: * michael@0: * @note This is currently supported only for michael@0: * http://xml.org/sax/features/namespace-prefixes . All other michael@0: * features will result in a NOT_IMPLEMENTED exception. michael@0: */ michael@0: void setFeature(in AString name, in boolean value); michael@0: michael@0: /** michael@0: * Look up the value of a feature flag. michael@0: * michael@0: * The feature name is any fully-qualified URI. It is michael@0: * possible for an XMLReader to recognize a feature name but michael@0: * temporarily be unable to return its value. michael@0: * Some feature values may be available only in specific michael@0: * contexts, such as before, during, or after a parse. michael@0: * michael@0: * All XMLReaders are required to recognize the michael@0: * http://xml.org/sax/features/namespaces and the michael@0: * http://xml.org/sax/features/namespace-prefixes feature names. michael@0: * michael@0: * @param name String flag for a parser feature. michael@0: * michael@0: * @note This is currently supported only for michael@0: * http://xml.org/sax/features/namespace-prefixes . All other michael@0: * features will result in a NOT_IMPLEMENTED exception. michael@0: */ michael@0: boolean getFeature(in AString name); michael@0: michael@0: /** michael@0: * Set the value of a property. NOT CURRENTLY IMPLEMENTED. michael@0: * michael@0: * The property name is any fully-qualified URI. It is possible michael@0: * for an XMLReader to recognize a property name but to be unable to michael@0: * change the current value. Some property values may be immutable michael@0: * or mutable only in specific contexts, such as before, during, or michael@0: * after a parse. michael@0: * michael@0: * XMLReaders are not required to recognize setting any specific michael@0: * property names, though a core set is defined by SAX2. michael@0: * michael@0: * This method is also the standard mechanism for setting michael@0: * extended handlers. michael@0: * michael@0: * @param name String flag for a parser feature michael@0: * @param value Turn the feature on/off. michael@0: */ michael@0: void setProperty(in AString name, in nsISupports value); michael@0: michael@0: /** michael@0: * Look up the value of a property. NOT CURRENTLY IMPLEMENTED. michael@0: * michael@0: * The property name is any fully-qualified URI. It is michael@0: * possible for an XMLReader to recognize a property name but michael@0: * temporarily be unable to return its value. michael@0: * Some property values may be available only in specific michael@0: * contexts, such as before, during, or after a parse. michael@0: * michael@0: * XMLReaders are not required to recognize any specific michael@0: * property names, though an initial core set is documented for michael@0: * SAX2. michael@0: * michael@0: * Implementors are free (and encouraged) to invent their own properties, michael@0: * using names built on their own URIs. michael@0: * michael@0: * @param name The property name, which is a fully-qualified URI. michael@0: * @return The current value of the property. michael@0: */ michael@0: boolean getProperty(in AString name); michael@0: michael@0: /** michael@0: * michael@0: * @param str The UTF16 string to be parsed michael@0: * @param contentType The content type of the string (see parseFromStream) michael@0: * michael@0: */ michael@0: void parseFromString(in AString str, in string contentType); michael@0: michael@0: /** michael@0: * michael@0: * @param stream The byte stream whose contents are parsed michael@0: * @param charset The character set that was used to encode the byte michael@0: * stream. NULL if not specified. michael@0: * @param contentType The content type of the string - either text/xml, michael@0: * application/xml, or application/xhtml+xml. michael@0: * Must not be NULL. michael@0: * michael@0: */ michael@0: void parseFromStream(in nsIInputStream stream, michael@0: in string charset, michael@0: in string contentType); michael@0: michael@0: /** michael@0: * Begin an asynchronous parse. This method initializes the parser, michael@0: * and must be called before any nsIStreamListener methods. It is michael@0: * then the caller's duty to call nsIStreamListener methods to drive michael@0: * the parser. Once this method is called, the caller must not call michael@0: * one of the other parse methods. michael@0: * michael@0: * @param observer The nsIRequestObserver to notify upon start or stop. michael@0: * Can be NULL. michael@0: */ michael@0: void parseAsync(in nsIRequestObserver observer); michael@0: };