The Tor Browser: comparison parser/xml/public/nsISAXContentHandler.idl

--1:000000000000
+:c48697120359
+/* -*- 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 "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
+};

The Tor Browser / file comparison

comparison: parser/xml/public/nsISAXContentHandler.idl

parser/xml/public/nsISAXContentHandler.idl