parser/xml/nsISAXContentHandler.idl

   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/. */
   5
   6 #include "nsISupports.idl"
   7
   8 interface nsISAXAttributes;
   9
  10 /**
  11  * Receive notification of the logical content of a document.
  12  *
  13  * This is the main interface that most SAX applications implement: if
  14  * the application needs to be informed of basic parsing events, it
  15  * implements this interface and registers an instance with the SAX
  16  * parser.  The parser uses the instance to report basic
  17  * document-related events like the start and end of elements and
  18  * character data.
  19  *
  20  * The order of events in this interface is very important, and
  21  * mirrors the order of information in the document itself.  For
  22  * example, all of an element's content (character data, processing
  23  * instructions, and/or subelements) will appear, in order, between
  24  * the startElement event and the corresponding endElement event.
  25  */
  26 [scriptable, uuid(2a99c757-dfee-4806-bff3-f721440412e0)]
  27 interface nsISAXContentHandler : nsISupports
  28 {
  29   /**
  30    * Receive notification of the beginning of a document.
  31    *
  32    * The SAX parser will invoke this method only once, before any
  33    * other event callbacks.
  34    */
  35   void startDocument();
  36
  37   /**
  38    * Receive notification of the end of a document.
  39    *
  40    * There is an apparent contradiction between the documentation for
  41    * this method and the documentation for ErrorHandler.fatalError().
  42    * Until this ambiguity is resolved in a future major release,
  43    * clients should make no assumptions about whether endDocument()
  44    * will or will not be invoked when the parser has reported a
  45    * fatalError() or thrown an exception.
  46    *
  47    * The SAX parser will invoke this method only once, and it will be
  48    * the last method invoked during the parse.  The parser shall not
  49    * invoke this method until it has either abandoned parsing (because
  50    * of an unrecoverable error) or reached the end of input.
  51    */
  52   void endDocument();
  53
  54   /**
  55    * Receive notification of the beginning of an element.
  56    *
  57    * The Parser will invoke this method at the beginning of every
  58    * element in the XML document; there will be a corresponding
  59    * endElement event for every startElement event (even when the
  60    * element is empty). All of the element's content will be reported,
  61    * in order, before the corresponding endElement event.
  62    *
  63    * This event allows up to three name components for each element:
  64    *
  65    * 1.) the Namespace URI;
  66    * 2.) the local name; and
  67    * 3.) the qualified (prefixed) name.
  68    *
  69    * Any or all of these may be provided, depending on the values of
  70    * the http://xml.org/sax/features/namespaces and the
  71    * http://xml.org/sax/features/namespace-prefixes properties:
  72    *
  73    * The Namespace URI and local name are required when the namespaces
  74    * property is true (the default), and are optional when the
  75    * namespaces property is false (if one is specified, both must be);
  76    *
  77    * The qualified name is required when the namespace-prefixes
  78    * property is true, and is optional when the namespace-prefixes
  79    * property is false (the default).
  80    *
  81    * Note that the attribute list provided will contain only
  82    * attributes with explicit values (specified or defaulted):
  83    * #IMPLIED attributes will be omitted.  The attribute list will
  84    * contain attributes used for Namespace declarations (xmlns*
  85    * attributes) only if the
  86    * http://xml.org/sax/features/namespace-prefixes property is true
  87    * (it is false by default, and support for a true value is
  88    * optional).
  89    *
  90    * @param uri the Namespace URI, or the empty string if the
  91    *        element has no Namespace URI or if Namespace
  92    *        processing is not being performed
  93    * @param localName the local name (without prefix), or the
  94    *        empty string if Namespace processing is not being
  95    *        performed
  96    * @param qName the qualified name (with prefix), or the
  97    *        empty string if qualified names are not available
  98    * @param atts the attributes attached to the element.  If
  99    *        there are no attributes, it shall be an empty
 100    *        SAXAttributes object.  The value of this object after
 101    *        startElement returns is undefined
 102    */
 103   void startElement(in AString uri, in AString localName,
 104                     in AString qName, in nsISAXAttributes attributes);
 105
 106   /**
 107    * Receive notification of the end of an element.
 108    *
 109    * The SAX parser will invoke this method at the end of every
 110    * element in the XML document; there will be a corresponding
 111    * startElement event for every endElement event (even when the
 112    * element is empty).
 113    *
 114    * For information on the names, see startElement.
 115    *
 116    * @param uri the Namespace URI, or the empty string if the
 117    *        element has no Namespace URI or if Namespace
 118    *        processing is not being performed
 119    * @param localName the local name (without prefix), or the
 120    *        empty string if Namespace processing is not being
 121    *        performed
 122    * @param qName the qualified XML name (with prefix), or the
 123    *        empty string if qualified names are not available
 124    */
 125   void endElement(in AString uri, in AString localName, in AString qName);
 126
 127   /**
 128    * Receive notification of character data.
 129    *
 130    * The Parser will call this method to report each chunk of
 131    * character data.  SAX parsers may return all contiguous character
 132    * data in a single chunk, or they may split it into several chunks;
 133    * however, all of the characters in any single event must come from
 134    * the same external entity so that the Locator provides useful
 135    * information.
 136    *
 137    * Note that some parsers will report whitespace in element
 138    * content using the ignorableWhitespace method rather than this one
 139    * (validating parsers must do so).
 140    *
 141    * @param value the characters from the XML document
 142    */
 143   void characters(in AString value);
 144
 145   /**
 146    * Receive notification of a processing instruction.
 147    *
 148    * The Parser will invoke this method once for each processing
 149    * instruction found: note that processing instructions may occur
 150    * before or after the main document element.
 151    *
 152    * A SAX parser must never report an XML declaration (XML 1.0,
 153    * section 2.8) or a text declaration (XML 1.0, section 4.3.1) using
 154    * this method.
 155    *
 156    * @param target the processing instruction target
 157    * @param data the processing instruction data, or null if
 158    *        none was supplied.  The data does not include any
 159    *        whitespace separating it from the target
 160    */
 161   void processingInstruction(in AString target, in AString data);
 162
 163   /**
 164    * Receive notification of ignorable whitespace in element content.
 165    *
 166    * Validating Parsers must use this method to report each chunk of
 167    * whitespace in element content (see the W3C XML 1.0
 168    * recommendation, section 2.10): non-validating parsers may also
 169    * use this method if they are capable of parsing and using content
 170    * models.
 171    *
 172    * SAX parsers may return all contiguous whitespace in a single
 173    * chunk, or they may split it into several chunks; however, all of
 174    * the characters in any single event must come from the same
 175    * external entity, so that the Locator provides useful information.
 176    *
 177    * @param whitespace the characters from the XML document
 178    */
 179   void ignorableWhitespace(in AString whitespace);
 180
 181   /**
 182    * Begin the scope of a prefix-URI Namespace mapping.
 183    *
 184    * The information from this event is not necessary for normal
 185    * Namespace processing: the SAX XML reader will automatically
 186    * replace prefixes for element and attribute names when the
 187    * http://xml.org/sax/features/namespaces feature is
 188    * true (the default).
 189    *
 190    * There are cases, however, when applications need to use prefixes
 191    * in character data or in attribute values, where they cannot
 192    * safely be expanded automatically; the start/endPrefixMapping
 193    * event supplies the information to the application to expand
 194    * prefixes in those contexts itself, if necessary.
 195    *
 196    * Note that start/endPrefixMapping events are not guaranteed to be
 197    * properly nested relative to each other: all startPrefixMapping
 198    * events will occur immediately before the corresponding
 199    * startElement event, and all endPrefixMapping events will occur
 200    * immediately after the corresponding endElement event, but their
 201    * order is not otherwise guaranteed.
 202    *
 203    * There should never be start/endPrefixMapping events for the
 204    * "xml" prefix, since it is predeclared and immutable.
 205    *
 206    * @param prefix The Namespace prefix being declared. An empty
 207    *               string is used for the default element namespace,
 208    *               which has no prefix.
 209    * @param uri The Namespace URI the prefix is mapped to.
 210    */
 211   void startPrefixMapping(in AString prefix, in AString uri);
 212
 213   /**
 214    * End the scope of a prefix-URI mapping.
 215    *
 216    * See startPrefixMapping for details.  These events will always
 217    * occur immediately after the corresponding endElement event, but
 218    * the order of endPrefixMapping events is not otherwise guaranteed.
 219    *
 220    * @param prefix The prefix that was being mapped. This is the empty
 221    *               string when a default mapping scope ends.
 222    */
 223   void endPrefixMapping(in AString prefix);
 224   //XXX documentLocator
 225 };