/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

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