parser/xml/public/nsISAXErrorHandler.idl

   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 "nsISupports.idl"
  39
  40 interface nsISAXLocator;
  41
  42 /**
  43  * Basic interface for SAX error handlers.
  44  *
  45  * If a SAX application needs to implement customized error
  46  * handling, it must implement this interface and then register an
  47  * instance with the XML reader.  The parser will then report all
  48  * errors and warnings through this interface.
  49  *
  50  * WARNING: If an application does not register an ErrorHandler,
  51  * XML parsing errors will go unreported. In order to detect validity
  52  * errors, an ErrorHandler that does something with error() calls must
  53  * be registered.
  54  *
  55  */
  56 [scriptable, uuid(e02b6693-6cca-11da-be43-001422106990)]
  57 interface nsISAXErrorHandler: nsISupports {
  58
  59   /**
  60    * Receive notification of a recoverable error.
  61    *
  62    * This corresponds to the definition of "error" in section 1.2
  63    * of the W3C XML 1.0 Recommendation. For example, a validating
  64    * parser would use this callback to report the violation of a
  65    * validity constraint. The default behaviour is to take no
  66    * action.
  67    *
  68    * The SAX parser must continue to provide normal parsing events
  69    * after invoking this method: it should still be possible for the
  70    * application to process the document through to the end. If the
  71    * application cannot do so, then the parser should report a fatal
  72    * error even if the XML recommendation does not require it to do
  73    * so.
  74    *
  75    * Filters may use this method to report other, non-XML errors as
  76    * well.
  77    *
  78    * @param locator The locator object for the error (may be null).
  79    * @param error The error message.
  80    */
  81   void error(in nsISAXLocator locator, in AString error);
  82
  83   /**
  84    * Receive notification of a non-recoverable error.
  85    *
  86    * There is an apparent contradiction between the documentation
  87    * for this method and the documentation for
  88    * ContentHandler.endDocument(). Until this ambiguity is resolved in
  89    * a future major release, clients should make no assumptions about
  90    * whether endDocument() will or will not be invoked when the parser
  91    * has reported a fatalError() or thrown an exception.
  92    *
  93    * This corresponds to the definition of "fatal error" in section
  94    * 1.2 of the W3C XML 1.0 Recommendation. For example, a parser
  95    * would use this callback to report the violation of a
  96    * well-formedness constraint.
  97    *
  98    * The application must assume that the document is unusable
  99    * after the parser has invoked this method, and should continue (if
 100    * at all) only for the sake of collecting additional error
 101    * messages: in fact, SAX parsers are free to stop reporting any
 102    * other events once this method has been invoked.
 103    *
 104    * @param locator The locator object for the error (may be null).
 105    * @param error The error message.
 106    */
 107   void fatalError(in nsISAXLocator locator, in AString error);
 108
 109   /**
 110    * Receive notification of a warning.
 111    *
 112    * SAX parsers will use this method to report conditions that are
 113    * not errors or fatal errors as defined by the XML
 114    * recommendation. The default behaviour is to take no action.
 115    *
 116    * The SAX parser must continue to provide normal parsing events
 117    * after invoking this method: it should still be possible for the
 118    * application to process the document through to the end.
 119    *
 120    * Filters may use this method to report other, non-XML warnings
 121    * as well.
 122    *
 123    * @param locator The locator object for the warning (may be null).
 124    * @param error The warning message.
 125    */
 126   void ignorableWarning(in nsISAXLocator locator, in AString error);
 127 };