diff options
Diffstat (limited to 'parser/xml/nsISAXContentHandler.idl')
| -rw-r--r-- | parser/xml/nsISAXContentHandler.idl | 225 |
1 files changed, 225 insertions, 0 deletions
diff --git a/parser/xml/nsISAXContentHandler.idl b/parser/xml/nsISAXContentHandler.idl new file mode 100644 index 0000000000..43b7e48c5b --- /dev/null +++ b/parser/xml/nsISAXContentHandler.idl @@ -0,0 +1,225 @@ +/* -*- 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 +}; |