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) 2006
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
38 #include "nsISupports.idl"
39
40 /**
41 * SAX2 extension handler for lexical events.
42 *
43 * This is an extension handler for SAX2 to provide lexical
44 * information about an XML document, such as comments and CDATA
45 * section boundaries.
46 *
47 * The events in the lexical handler apply to the entire document,
48 * not just to the document element, and all lexical handler events
49 * must appear between the content handler's startDocument and
50 * endDocument events.
51 */
52 [scriptable, uuid(23c26a56-adff-440c-8caf-95c2dc2e399b)]
53 interface nsISAXLexicalHandler : nsISupports {
54
55 /**
56 * Report an XML comment anywhere in the document.
57 *
58 * This callback will be used for comments inside or outside the
59 * document element, including comments in the external DTD subset
60 * (if read). Comments in the DTD must be properly nested inside
61 * start/endDTD and start/endEntity events (if used).
62 *
63 * @param chars The characters in the comment.
64 */
65 void comment(in AString chars);
66
67 /**
68 * Report the start of DTD declarations, if any.
69 *
70 * This method is intended to report the beginning of the
71 * DOCTYPE declaration; if the document has no DOCTYPE declaration,
72 * this method will not be invoked.
73 *
74 * All declarations reported through DTDHandler or DeclHandler
75 * events must appear between the startDTD and endDTD events.
76 * Declarations are assumed to belong to the internal DTD subset
77 * unless they appear between startEntity and endEntity events.
78 * Comments and processing instructions from the DTD should also be
79 * reported between the startDTD and endDTD events, in their
80 * original order of (logical) occurrence; they are not required to
81 * appear in their correct locations relative to DTDHandler or
82 * DeclHandler events, however.
83 *
84 * Note that the start/endDTD events will appear within the
85 * start/endDocument events from ContentHandler and before the first
86 * startElement event.
87 *
88 * @param name The document type name.
89 * @param publicId The declared public identifier for the
90 * external DTD subset, or null if none was declared.
91 * @param systemId The declared system identifier for the
92 * external DTD subset, or null if none was declared.
93 * (Note that this is not resolved against the document
94 * base URI.)
95 */
96 void startDTD(in AString name, in AString publicId, in AString systemId);
97
98 /**
99 * Report the end of DTD declarations.
100 *
101 * This method is intended to report the end of the
102 * DOCTYPE declaration; if the document has no DOCTYPE declaration,
103 * this method will not be invoked.
104 */
105 void endDTD();
106
107 /**
108 * Report the start of a CDATA section.
109 *
110 * The contents of the CDATA section will be reported through the
111 * regular characters event; this event is intended only to report
112 * the boundary.
113 */
114 void startCDATA();
115
116 /**
117 * Report the end of a CDATA section.
118 */
119 void endCDATA();
120
121 /**
122 * Report the beginning of some internal and external XML entities.
123 *
124 * Because of the streaming event model that SAX uses, some
125 * entity boundaries cannot be reported under any circumstances:
126 *
127 * 1.) general entities within attribute values
128 * 2.) parameter entities within declarations
129 *
130 * These will be silently expanded, with no indication of where
131 * the original entity boundaries were.
132 *
133 * Note also that the boundaries of character references (which
134 * are not really entities anyway) are not reported.
135 *
136 * All start/endEntity events must be properly nested.
137 *
138 * @param name The name of the entity. If it is a parameter
139 * entity, the name will begin with '%', and if it is the
140 * external DTD subset, it will be "[dtd]".
141 */
142 void startEntity(in AString name);
143
144 /**
145 * Report the end of an entity.
146 *
147 * @param name The name of the entity that is ending.
148 */
149 void endEntity(in AString name);
150 };