/parser/xml/public/nsISAXContentHandler.idl
http://github.com/zpao/v8monkey · IDL · 257 lines · 16 code · 11 blank · 230 comment · 0 complexity · 5982dcd665ead2d332de0596a9e70547 MD5 · raw file
- /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
- /* ***** BEGIN LICENSE BLOCK *****
- * Version: MPL 1.1/GPL 2.0/LGPL 2.1
- *
- * The contents of this file are subject to the Mozilla Public License Version
- * 1.1 (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- * http://www.mozilla.org/MPL/
- *
- * Software distributed under the License is distributed on an "AS IS" basis,
- * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
- * for the specific language governing rights and limitations under the
- * License.
- *
- * The Original Code is mozilla.org code.
- *
- * The Initial Developer of the Original Code is Robert Sayre.
- *
- * Portions created by the Initial Developer are Copyright (C) 2005
- * the Initial Developer. All Rights Reserved.
- *
- * Contributor(s):
- *
- * Alternatively, the contents of this file may be used under the terms of
- * either the GNU General Public License Version 2 or later (the "GPL"), or
- * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
- * in which case the provisions of the GPL or the LGPL are applicable instead
- * of those above. If you wish to allow use of your version of this file only
- * under the terms of either the GPL or the LGPL, and not to allow others to
- * use your version of this file under the terms of the MPL, indicate your
- * decision by deleting the provisions above and replace them with the notice
- * and other provisions required by the GPL or the LGPL. If you do not delete
- * the provisions above, a recipient may use your version of this file under
- * the terms of any one of the MPL, the GPL or the LGPL.
- *
- * ***** END LICENSE BLOCK ***** */
- #include "nsISupports.idl"
- interface nsISAXAttributes;
- /**
- * Receive notification of the logical content of a document.
- *
- * This is the main interface that most SAX applications implement: if
- * the application needs to be informed of basic parsing events, it
- * implements this interface and registers an instance with the SAX
- * parser. The parser uses the instance to report basic
- * document-related events like the start and end of elements and
- * character data.
- *
- * The order of events in this interface is very important, and
- * mirrors the order of information in the document itself. For
- * example, all of an element's content (character data, processing
- * instructions, and/or subelements) will appear, in order, between
- * the startElement event and the corresponding endElement event.
- */
- [scriptable, uuid(2a99c757-dfee-4806-bff3-f721440412e0)]
- interface nsISAXContentHandler : nsISupports
- {
- /**
- * Receive notification of the beginning of a document.
- *
- * The SAX parser will invoke this method only once, before any
- * other event callbacks.
- */
- void startDocument();
- /**
- * Receive notification of the end of a document.
- *
- * There is an apparent contradiction between the documentation for
- * this method and the documentation for ErrorHandler.fatalError().
- * Until this ambiguity is resolved in a future major release,
- * clients should make no assumptions about whether endDocument()
- * will or will not be invoked when the parser has reported a
- * fatalError() or thrown an exception.
- *
- * The SAX parser will invoke this method only once, and it will be
- * the last method invoked during the parse. The parser shall not
- * invoke this method until it has either abandoned parsing (because
- * of an unrecoverable error) or reached the end of input.
- */
- void endDocument();
-
- /**
- * Receive notification of the beginning of an element.
- *
- * The Parser will invoke this method at the beginning of every
- * element in the XML document; there will be a corresponding
- * endElement event for every startElement event (even when the
- * element is empty). All of the element's content will be reported,
- * in order, before the corresponding endElement event.
- *
- * This event allows up to three name components for each element:
- *
- * 1.) the Namespace URI;
- * 2.) the local name; and
- * 3.) the qualified (prefixed) name.
- *
- * Any or all of these may be provided, depending on the values of
- * the http://xml.org/sax/features/namespaces and the
- * http://xml.org/sax/features/namespace-prefixes properties:
- *
- * The Namespace URI and local name are required when the namespaces
- * property is true (the default), and are optional when the
- * namespaces property is false (if one is specified, both must be);
- *
- * The qualified name is required when the namespace-prefixes
- * property is true, and is optional when the namespace-prefixes
- * property is false (the default).
- *
- * Note that the attribute list provided will contain only
- * attributes with explicit values (specified or defaulted):
- * #IMPLIED attributes will be omitted. The attribute list will
- * contain attributes used for Namespace declarations (xmlns*
- * attributes) only if the
- * http://xml.org/sax/features/namespace-prefixes property is true
- * (it is false by default, and support for a true value is
- * optional).
- *
- * @param uri the Namespace URI, or the empty string if the
- * element has no Namespace URI or if Namespace
- * processing is not being performed
- * @param localName the local name (without prefix), or the
- * empty string if Namespace processing is not being
- * performed
- * @param qName the qualified name (with prefix), or the
- * empty string if qualified names are not available
- * @param atts the attributes attached to the element. If
- * there are no attributes, it shall be an empty
- * SAXAttributes object. The value of this object after
- * startElement returns is undefined
- */
- void startElement(in AString uri, in AString localName,
- in AString qName, in nsISAXAttributes attributes);
- /**
- * Receive notification of the end of an element.
- *
- * The SAX parser will invoke this method at the end of every
- * element in the XML document; there will be a corresponding
- * startElement event for every endElement event (even when the
- * element is empty).
- *
- * For information on the names, see startElement.
- *
- * @param uri the Namespace URI, or the empty string if the
- * element has no Namespace URI or if Namespace
- * processing is not being performed
- * @param localName the local name (without prefix), or the
- * empty string if Namespace processing is not being
- * performed
- * @param qName the qualified XML name (with prefix), or the
- * empty string if qualified names are not available
- */
- void endElement(in AString uri, in AString localName, in AString qName);
- /**
- * Receive notification of character data.
- *
- * The Parser will call this method to report each chunk of
- * character data. SAX parsers may return all contiguous character
- * data in a single chunk, or they may split it into several chunks;
- * however, all of the characters in any single event must come from
- * the same external entity so that the Locator provides useful
- * information.
- *
- * Note that some parsers will report whitespace in element
- * content using the ignorableWhitespace method rather than this one
- * (validating parsers must do so).
- *
- * @param value the characters from the XML document
- */
- void characters(in AString value);
- /**
- * Receive notification of a processing instruction.
- *
- * The Parser will invoke this method once for each processing
- * instruction found: note that processing instructions may occur
- * before or after the main document element.
- *
- * A SAX parser must never report an XML declaration (XML 1.0,
- * section 2.8) or a text declaration (XML 1.0, section 4.3.1) using
- * this method.
- *
- * @param target the processing instruction target
- * @param data the processing instruction data, or null if
- * none was supplied. The data does not include any
- * whitespace separating it from the target
- */
- void processingInstruction(in AString target, in AString data);
- /**
- * Receive notification of ignorable whitespace in element content.
- *
- * Validating Parsers must use this method to report each chunk of
- * whitespace in element content (see the W3C XML 1.0
- * recommendation, section 2.10): non-validating parsers may also
- * use this method if they are capable of parsing and using content
- * models.
- *
- * SAX parsers may return all contiguous whitespace in a single
- * chunk, or they may split it into several chunks; however, all of
- * the characters in any single event must come from the same
- * external entity, so that the Locator provides useful information.
- *
- * @param whitespace the characters from the XML document
- */
- void ignorableWhitespace(in AString whitespace);
- /**
- * Begin the scope of a prefix-URI Namespace mapping.
- *
- * The information from this event is not necessary for normal
- * Namespace processing: the SAX XML reader will automatically
- * replace prefixes for element and attribute names when the
- * http://xml.org/sax/features/namespaces feature is
- * true (the default).
- *
- * There are cases, however, when applications need to use prefixes
- * in character data or in attribute values, where they cannot
- * safely be expanded automatically; the start/endPrefixMapping
- * event supplies the information to the application to expand
- * prefixes in those contexts itself, if necessary.
- *
- * Note that start/endPrefixMapping events are not guaranteed to be
- * properly nested relative to each other: all startPrefixMapping
- * events will occur immediately before the corresponding
- * startElement event, and all endPrefixMapping events will occur
- * immediately after the corresponding endElement event, but their
- * order is not otherwise guaranteed.
- *
- * There should never be start/endPrefixMapping events for the
- * "xml" prefix, since it is predeclared and immutable.
- *
- * @param prefix The Namespace prefix being declared. An empty
- * string is used for the default element namespace,
- * which has no prefix.
- * @param uri The Namespace URI the prefix is mapped to.
- */
- void startPrefixMapping(in AString prefix, in AString uri);
- /**
- * End the scope of a prefix-URI mapping.
- *
- * See startPrefixMapping for details. These events will always
- * occur immediately after the corresponding endElement event, but
- * the order of endPrefixMapping events is not otherwise guaranteed.
- *
- * @param prefix The prefix that was being mapped. This is the empty
- * string when a default mapping scope ends.
- */
- void endPrefixMapping(in AString prefix);
- //XXX documentLocator
- };