/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsIStreamListener.idl"

interface nsIInputStream;
interface nsIRequestObserver;
interface nsIURI;

interface nsISAXContentHandler;
interface nsISAXDTDHandler;
interface nsISAXErrorHandler;
interface nsISAXLexicalHandler;
interface nsIMozSAXXMLDeclarationHandler;

/**
 * Interface for reading an XML document using callbacks.
 *
 * NOTE: This file (and related ones) used to implement a full-featured SAX XML
 * parser. But we have few uses of this interface and the ones we have only use
 * a fraction of the full SAX functionality. So in bug 1416038 we removed a lot
 * of it. See the changes associated with that bug if you need to reintroduce
 * any of that functionality.
 *
 * nsISAXXMLReader is the interface that an XML parser's SAX2
 * driver must implement.  This interface allows an application to set
 * and query features and properties in the parser, to register event
 * handlers for document processing, and to initiate a document
 * parse.
 */
[scriptable, uuid(5b1de802-9091-454f-9972-5753c0d0c70e)]
interface nsISAXXMLReader : nsIStreamListener {

  /**
   * The base URI.
   */
  attribute nsIURI baseURI;

  /**
   * If the application does not register a content handler, all
   * content events reported by the SAX parser will be silently
   * ignored.
   *
   * Applications may register a new or different handler in the
   * middle of a parse, and the SAX parser must begin using the new
   * handler immediately.
   */
  attribute nsISAXContentHandler contentHandler;

  /**
   * If the application does not register an error handler, all
   * error events reported by the SAX parser will be silently ignored;
   * however, normal processing may not continue.  It is highly
   * recommended that all SAX applications implement an error handler
   * to avoid unexpected bugs.
   *
   * Applications may register a new or different handler in the
   * middle of a parse, and the SAX parser must begin using the new
   * handler immediately.
   */
  attribute nsISAXErrorHandler errorHandler;
  
  /**
   * Begin an asynchronous parse. This method initializes the parser,
   * and must be called before any nsIStreamListener methods. It is
   * then the caller's duty to call nsIStreamListener methods to drive
   * the parser. Once this method is called, the caller must not call
   * one of the other parse methods.
   *
   * @param observer The nsIRequestObserver to notify upon start or stop.
   *                 Can be NULL.
   */
  void parseAsync(in nsIRequestObserver observer);
};