1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/parser/xml/public/nsISAXContentHandler.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,225 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsISAXAttributes;
1.12 +
1.13 +/**
1.14 + * Receive notification of the logical content of a document.
1.15 + *
1.16 + * This is the main interface that most SAX applications implement: if
1.17 + * the application needs to be informed of basic parsing events, it
1.18 + * implements this interface and registers an instance with the SAX
1.19 + * parser. The parser uses the instance to report basic
1.20 + * document-related events like the start and end of elements and
1.21 + * character data.
1.22 + *
1.23 + * The order of events in this interface is very important, and
1.24 + * mirrors the order of information in the document itself. For
1.25 + * example, all of an element's content (character data, processing
1.26 + * instructions, and/or subelements) will appear, in order, between
1.27 + * the startElement event and the corresponding endElement event.
1.28 + */
1.29 +[scriptable, uuid(2a99c757-dfee-4806-bff3-f721440412e0)]
1.30 +interface nsISAXContentHandler : nsISupports
1.31 +{
1.32 + /**
1.33 + * Receive notification of the beginning of a document.
1.34 + *
1.35 + * The SAX parser will invoke this method only once, before any
1.36 + * other event callbacks.
1.37 + */
1.38 + void startDocument();
1.39 +
1.40 + /**
1.41 + * Receive notification of the end of a document.
1.42 + *
1.43 + * There is an apparent contradiction between the documentation for
1.44 + * this method and the documentation for ErrorHandler.fatalError().
1.45 + * Until this ambiguity is resolved in a future major release,
1.46 + * clients should make no assumptions about whether endDocument()
1.47 + * will or will not be invoked when the parser has reported a
1.48 + * fatalError() or thrown an exception.
1.49 + *
1.50 + * The SAX parser will invoke this method only once, and it will be
1.51 + * the last method invoked during the parse. The parser shall not
1.52 + * invoke this method until it has either abandoned parsing (because
1.53 + * of an unrecoverable error) or reached the end of input.
1.54 + */
1.55 + void endDocument();
1.56 +
1.57 + /**
1.58 + * Receive notification of the beginning of an element.
1.59 + *
1.60 + * The Parser will invoke this method at the beginning of every
1.61 + * element in the XML document; there will be a corresponding
1.62 + * endElement event for every startElement event (even when the
1.63 + * element is empty). All of the element's content will be reported,
1.64 + * in order, before the corresponding endElement event.
1.65 + *
1.66 + * This event allows up to three name components for each element:
1.67 + *
1.68 + * 1.) the Namespace URI;
1.69 + * 2.) the local name; and
1.70 + * 3.) the qualified (prefixed) name.
1.71 + *
1.72 + * Any or all of these may be provided, depending on the values of
1.73 + * the http://xml.org/sax/features/namespaces and the
1.74 + * http://xml.org/sax/features/namespace-prefixes properties:
1.75 + *
1.76 + * The Namespace URI and local name are required when the namespaces
1.77 + * property is true (the default), and are optional when the
1.78 + * namespaces property is false (if one is specified, both must be);
1.79 + *
1.80 + * The qualified name is required when the namespace-prefixes
1.81 + * property is true, and is optional when the namespace-prefixes
1.82 + * property is false (the default).
1.83 + *
1.84 + * Note that the attribute list provided will contain only
1.85 + * attributes with explicit values (specified or defaulted):
1.86 + * #IMPLIED attributes will be omitted. The attribute list will
1.87 + * contain attributes used for Namespace declarations (xmlns*
1.88 + * attributes) only if the
1.89 + * http://xml.org/sax/features/namespace-prefixes property is true
1.90 + * (it is false by default, and support for a true value is
1.91 + * optional).
1.92 + *
1.93 + * @param uri the Namespace URI, or the empty string if the
1.94 + * element has no Namespace URI or if Namespace
1.95 + * processing is not being performed
1.96 + * @param localName the local name (without prefix), or the
1.97 + * empty string if Namespace processing is not being
1.98 + * performed
1.99 + * @param qName the qualified name (with prefix), or the
1.100 + * empty string if qualified names are not available
1.101 + * @param atts the attributes attached to the element. If
1.102 + * there are no attributes, it shall be an empty
1.103 + * SAXAttributes object. The value of this object after
1.104 + * startElement returns is undefined
1.105 + */
1.106 + void startElement(in AString uri, in AString localName,
1.107 + in AString qName, in nsISAXAttributes attributes);
1.108 +
1.109 + /**
1.110 + * Receive notification of the end of an element.
1.111 + *
1.112 + * The SAX parser will invoke this method at the end of every
1.113 + * element in the XML document; there will be a corresponding
1.114 + * startElement event for every endElement event (even when the
1.115 + * element is empty).
1.116 + *
1.117 + * For information on the names, see startElement.
1.118 + *
1.119 + * @param uri the Namespace URI, or the empty string if the
1.120 + * element has no Namespace URI or if Namespace
1.121 + * processing is not being performed
1.122 + * @param localName the local name (without prefix), or the
1.123 + * empty string if Namespace processing is not being
1.124 + * performed
1.125 + * @param qName the qualified XML name (with prefix), or the
1.126 + * empty string if qualified names are not available
1.127 + */
1.128 + void endElement(in AString uri, in AString localName, in AString qName);
1.129 +
1.130 + /**
1.131 + * Receive notification of character data.
1.132 + *
1.133 + * The Parser will call this method to report each chunk of
1.134 + * character data. SAX parsers may return all contiguous character
1.135 + * data in a single chunk, or they may split it into several chunks;
1.136 + * however, all of the characters in any single event must come from
1.137 + * the same external entity so that the Locator provides useful
1.138 + * information.
1.139 + *
1.140 + * Note that some parsers will report whitespace in element
1.141 + * content using the ignorableWhitespace method rather than this one
1.142 + * (validating parsers must do so).
1.143 + *
1.144 + * @param value the characters from the XML document
1.145 + */
1.146 + void characters(in AString value);
1.147 +
1.148 + /**
1.149 + * Receive notification of a processing instruction.
1.150 + *
1.151 + * The Parser will invoke this method once for each processing
1.152 + * instruction found: note that processing instructions may occur
1.153 + * before or after the main document element.
1.154 + *
1.155 + * A SAX parser must never report an XML declaration (XML 1.0,
1.156 + * section 2.8) or a text declaration (XML 1.0, section 4.3.1) using
1.157 + * this method.
1.158 + *
1.159 + * @param target the processing instruction target
1.160 + * @param data the processing instruction data, or null if
1.161 + * none was supplied. The data does not include any
1.162 + * whitespace separating it from the target
1.163 + */
1.164 + void processingInstruction(in AString target, in AString data);
1.165 +
1.166 + /**
1.167 + * Receive notification of ignorable whitespace in element content.
1.168 + *
1.169 + * Validating Parsers must use this method to report each chunk of
1.170 + * whitespace in element content (see the W3C XML 1.0
1.171 + * recommendation, section 2.10): non-validating parsers may also
1.172 + * use this method if they are capable of parsing and using content
1.173 + * models.
1.174 + *
1.175 + * SAX parsers may return all contiguous whitespace in a single
1.176 + * chunk, or they may split it into several chunks; however, all of
1.177 + * the characters in any single event must come from the same
1.178 + * external entity, so that the Locator provides useful information.
1.179 + *
1.180 + * @param whitespace the characters from the XML document
1.181 + */
1.182 + void ignorableWhitespace(in AString whitespace);
1.183 +
1.184 + /**
1.185 + * Begin the scope of a prefix-URI Namespace mapping.
1.186 + *
1.187 + * The information from this event is not necessary for normal
1.188 + * Namespace processing: the SAX XML reader will automatically
1.189 + * replace prefixes for element and attribute names when the
1.190 + * http://xml.org/sax/features/namespaces feature is
1.191 + * true (the default).
1.192 + *
1.193 + * There are cases, however, when applications need to use prefixes
1.194 + * in character data or in attribute values, where they cannot
1.195 + * safely be expanded automatically; the start/endPrefixMapping
1.196 + * event supplies the information to the application to expand
1.197 + * prefixes in those contexts itself, if necessary.
1.198 + *
1.199 + * Note that start/endPrefixMapping events are not guaranteed to be
1.200 + * properly nested relative to each other: all startPrefixMapping
1.201 + * events will occur immediately before the corresponding
1.202 + * startElement event, and all endPrefixMapping events will occur
1.203 + * immediately after the corresponding endElement event, but their
1.204 + * order is not otherwise guaranteed.
1.205 + *
1.206 + * There should never be start/endPrefixMapping events for the
1.207 + * "xml" prefix, since it is predeclared and immutable.
1.208 + *
1.209 + * @param prefix The Namespace prefix being declared. An empty
1.210 + * string is used for the default element namespace,
1.211 + * which has no prefix.
1.212 + * @param uri The Namespace URI the prefix is mapped to.
1.213 + */
1.214 + void startPrefixMapping(in AString prefix, in AString uri);
1.215 +
1.216 + /**
1.217 + * End the scope of a prefix-URI mapping.
1.218 + *
1.219 + * See startPrefixMapping for details. These events will always
1.220 + * occur immediately after the corresponding endElement event, but
1.221 + * the order of endPrefixMapping events is not otherwise guaranteed.
1.222 + *
1.223 + * @param prefix The prefix that was being mapped. This is the empty
1.224 + * string when a default mapping scope ends.
1.225 + */
1.226 + void endPrefixMapping(in AString prefix);
1.227 + //XXX documentLocator
1.228 +};
