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