source: NonGTP/Xerces/xerces/include/xercesc/sax2/ContentHandler.hpp @ 358

Revision 358, 13.5 KB checked in by bittner, 19 years ago (diff)

xerces added

Line 
1/*
2 * Copyright 1999-2000,2004 The Apache Software Foundation.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17/*
18 * $Log: ContentHandler.hpp,v $
19 * Revision 1.4  2004/09/08 13:56:20  peiyongz
20 * Apache License Version 2.0
21 *
22 * Revision 1.3  2003/03/07 18:10:30  tng
23 * Return a reference instead of void for operator=
24 *
25 * Revision 1.2  2002/11/04 14:55:45  tng
26 * C++ Namespace Support.
27 *
28 * Revision 1.1.1.1  2002/02/01 22:22:09  peiyongz
29 * sane_include
30 *
31 * Revision 1.4  2000/12/14 18:50:05  tng
32 * Fix API document generation warning: "Warning: end of member group without matching begin"
33 *
34 * Revision 1.3  2000/08/09 22:19:29  jpolast
35 * many conformance & stability changes:
36 *   - ContentHandler::resetDocument() removed
37 *   - attrs param of ContentHandler::startDocument() made const
38 *   - SAXExceptions thrown now have msgs
39 *   - removed duplicate function signatures that had 'const'
40 *       [ eg: getContentHander() ]
41 *   - changed getFeature and getProperty to apply to const objs
42 *   - setProperty now takes a void* instead of const void*
43 *   - SAX2XMLReaderImpl does not inherit from SAXParser anymore
44 *   - Reuse Validator (http://apache.org/xml/features/reuse-validator) implemented
45 *   - Features & Properties now read-only during parse
46 *
47 * Revision 1.2  2000/08/07 18:21:27  jpolast
48 * change SAX_EXPORT module to SAX2_EXPORT
49 *
50 * Revision 1.1  2000/08/02 18:02:34  jpolast
51 * initial checkin of sax2 implementation
52 * submitted by Simon Fell (simon@fell.com)
53 * and Joe Polastre (jpolast@apache.org)
54 *
55 *
56 */
57
58
59#ifndef CONTENTHANDLER_HPP
60#define CONTENTHANDLER_HPP
61
62#include <xercesc/util/XercesDefs.hpp>
63
64XERCES_CPP_NAMESPACE_BEGIN
65
66class Attributes;
67class Locator;
68
69/**
70  * Receive notification of general document events.
71  *
72  * <p>This is the main interface that most SAX2 applications
73  * implement: if the application needs to be informed of basic parsing
74  * events, it implements this interface and registers an instance with
75  * the SAX2 parser using the setDocumentHandler method.  The parser
76  * uses the instance to report basic document-related events like
77  * the start and end of elements and character data.</p>
78  *
79  * <p>The order of events in this interface is very important, and
80  * mirrors the order of information in the document itself.  For
81  * example, all of an element's content (character data, processing
82  * instructions, and/or subelements) will appear, in order, between
83  * the startElement event and the corresponding endElement event.</p>
84  *
85  * <p>Application writers who do not want to implement the entire
86  * interface while can derive a class from Sax2HandlerBase, which implements
87  * the default functionality; parser writers can instantiate
88  * Sax2HandlerBase to obtain a default handler.  The application can find
89  * the location of any document event using the Locator interface
90  * supplied by the Parser through the setDocumentLocator method.</p>
91  *
92  * @see Parser#setDocumentHandler
93  * @see Locator#Locator
94  * @see Sax2HandlerBase#Sax2HandlerBase
95  */
96
97class SAX2_EXPORT ContentHandler
98{
99public:
100    /** @name Constructors and Destructor */
101    //@{
102    /** Default constructor */
103    ContentHandler()
104    {
105    }
106
107    /** Destructor */
108    virtual ~ContentHandler()
109    {
110    }
111    //@}
112
113    /** @name The virtual document handler interface */
114
115    //@{
116   /**
117    * Receive notification of character data.
118    *
119    * <p>The Parser will call this method to report each chunk of
120    * character data.  SAX parsers may return all contiguous character
121    * data in a single chunk, or they may split it into several
122    * chunks; however, all of the characters in any single event
123    * must come from the same external entity, so that the Locator
124    * provides useful information.</p>
125    *
126    * <p>The application must not attempt to read from the array
127    * outside of the specified range.</p>
128    *
129    * <p>Note that some parsers will report whitespace using the
130    * ignorableWhitespace() method rather than this one (validating
131    * parsers must do so).</p>
132    *
133    * @param chars The characters from the XML document.
134    * @param length The number of characters to read from the array.
135    * @exception SAXException Any SAX exception, possibly
136    *            wrapping another exception.
137    * @see #ignorableWhitespace
138    * @see Locator#Locator
139    */
140    virtual void characters
141    (
142        const   XMLCh* const    chars
143        , const unsigned int    length
144    ) = 0;
145
146  /**
147    * Receive notification of the end of a document.
148    *
149    * <p>The SAX parser will invoke this method only once, and it will
150    * be the last method invoked during the parse.  The parser shall
151    * not invoke this method until it has either abandoned parsing
152    * (because of an unrecoverable error) or reached the end of
153    * input.</p>
154    *
155    * @exception SAXException Any SAX exception, possibly
156    *            wrapping another exception.
157    */
158    virtual void endDocument () = 0;
159
160  /**
161    * Receive notification of the end of an element.
162    *
163    * <p>The SAX parser will invoke this method at the end of every
164    * element in the XML document; there will be a corresponding
165    * startElement() event for every endElement() event (even when the
166    * element is empty).</p>
167    *
168    * @param uri The URI of the asscioated namespace for this element
169        * @param localname The local part of the element name
170        * @param qname The QName of this element
171    * @exception SAXException Any SAX exception, possibly
172    *            wrapping another exception.
173    */
174    virtual void endElement
175        (
176                const XMLCh* const uri,
177                const XMLCh* const localname,
178                const XMLCh* const qname
179        ) = 0;
180
181  /**
182    * Receive notification of ignorable whitespace in element content.
183    *
184    * <p>Validating Parsers must use this method to report each chunk
185    * of ignorable whitespace (see the W3C XML 1.0 recommendation,
186    * section 2.10): non-validating parsers may also use this method
187    * if they are capable of parsing and using content models.</p>
188    *
189    * <p>SAX parsers may return all contiguous whitespace in a single
190    * chunk, or they may split it into several chunks; however, all of
191    * the characters in any single event must come from the same
192    * external entity, so that the Locator provides useful
193    * information.</p>
194    *
195    * <p>The application must not attempt to read from the array
196    * outside of the specified range.</p>
197    *
198    * @param chars The characters from the XML document.
199    * @param length The number of characters to read from the array.
200    * @exception SAXException Any SAX exception, possibly
201    *            wrapping another exception.
202    * @see #characters
203    */
204    virtual void ignorableWhitespace
205    (
206        const   XMLCh* const    chars
207        , const unsigned int    length
208    ) = 0;
209
210  /**
211    * Receive notification of a processing instruction.
212    *
213    * <p>The Parser will invoke this method once for each processing
214    * instruction found: note that processing instructions may occur
215    * before or after the main document element.</p>
216    *
217    * <p>A SAX parser should never report an XML declaration (XML 1.0,
218    * section 2.8) or a text declaration (XML 1.0, section 4.3.1)
219    * using this method.</p>
220    *
221    * @param target The processing instruction target.
222    * @param data The processing instruction data, or null if
223    *        none was supplied.
224    * @exception SAXException Any SAX exception, possibly
225    *            wrapping another exception.
226    */
227    virtual void processingInstruction
228    (
229        const   XMLCh* const    target
230        , const XMLCh* const    data
231    ) = 0;
232
233  /**
234    * Receive an object for locating the origin of SAX document events.
235    *
236    * SAX parsers are strongly encouraged (though not absolutely
237    * required) to supply a locator: if it does so, it must supply
238    * the locator to the application by invoking this method before
239    * invoking any of the other methods in the DocumentHandler
240    * interface.
241    *
242    * The locator allows the application to determine the end
243    * position of any document-related event, even if the parser is
244    * not reporting an error.  Typically, the application will
245    * use this information for reporting its own errors (such as
246    * character content that does not match an application's
247    * business rules). The information returned by the locator
248    * is probably not sufficient for use with a search engine.
249    *
250    * Note that the locator will return correct information only
251    * during the invocation of the events in this interface. The
252    * application should not attempt to use it at any other time.
253    *
254    * @param locator An object that can return the location of
255    *                any SAX document event. The object is only
256    *                'on loan' to the client code and they are not
257    *                to attempt to delete or modify it in any way!
258    *
259    * @see Locator#Locator
260    */
261    virtual void setDocumentLocator(const Locator* const locator) = 0;
262
263  /**
264    * Receive notification of the beginning of a document.
265    *
266    * <p>The SAX parser will invoke this method only once, before any
267    * other methods in this interface or in DTDHandler (except for
268    * setDocumentLocator).</p>
269    *
270    * @exception SAXException Any SAX exception, possibly
271    *            wrapping another exception.
272    */
273    virtual void startDocument() = 0;
274
275  /**
276    * Receive notification of the beginning of an element.
277    *
278    * <p>The Parser will invoke this method at the beginning of every
279    * element in the XML document; there will be a corresponding
280    * endElement() event for every startElement() event (even when the
281    * element is empty). All of the element's content will be
282    * reported, in order, before the corresponding endElement()
283    * event.</p>
284    *
285    * <p>Note that the attribute list provided will
286    * contain only attributes with explicit values (specified or
287    * defaulted): #IMPLIED attributes will be omitted.</p>
288    *
289    * @param uri The URI of the asscioated namespace for this element
290        * @param localname The local part of the element name
291        * @param qname The QName of this element
292    * @param attrs The attributes attached to the element, if any.
293    * @exception SAXException Any SAX exception, possibly
294    *            wrapping another exception.
295    * @see #endElement
296    * @see Attributes#Attributes
297    */
298    virtual void startElement
299    (
300        const   XMLCh* const    uri,
301        const   XMLCh* const    localname,
302        const   XMLCh* const    qname,
303        const   Attributes&     attrs
304    ) = 0;
305
306  /**
307    * Receive notification of the start of an namespace prefix mapping.
308    *
309    * <p>By default, do nothing.  Application writers may override this
310    * method in a subclass to take specific actions at the start of
311    * each namespace prefix mapping.</p>
312    *
313    * @param prefix The namespace prefix used
314    * @param uri The namespace URI used.
315    * @exception SAXException Any SAX exception, possibly
316    *            wrapping another exception.
317    */
318        virtual void startPrefixMapping
319        (
320                const   XMLCh* const    prefix,
321                const   XMLCh* const    uri
322        ) = 0 ;
323
324  /**
325    * Receive notification of the end of an namespace prefix mapping.
326    *
327    * <p>By default, do nothing.  Application writers may override this
328    * method in a subclass to take specific actions at the end of
329    * each namespace prefix mapping.</p>
330    *
331    * @param prefix The namespace prefix used
332    * @exception SAXException Any SAX exception, possibly
333    *            wrapping another exception.
334    */
335        virtual void endPrefixMapping
336        (
337                const   XMLCh* const    prefix
338        ) = 0 ;
339
340  /**
341    * Receive notification of a skipped entity
342    *
343    * <p>The parser will invoke this method once for each entity
344        * skipped.  All processors may skip external entities,
345        * depending on the values of the features:<br>
346        * http://xml.org/sax/features/external-general-entities<br>
347        * http://xml.org/sax/features/external-parameter-entities</p>
348        *
349        * <p>Note: Xerces (specifically) never skips any entities, regardless
350        * of the above features.  This function is never called in the
351        * Xerces implementation of SAX2.</p>
352    *
353        * <p>Introduced with SAX2</p>
354        *
355    * @param name The name of the skipped entity.  If it is a parameter entity,
356        * the name will begin with %, and if it is the external DTD subset,
357        * it will be the string [dtd].
358    * @exception SAXException Any SAX exception, possibly
359    *            wrapping another exception.
360    */
361        virtual void skippedEntity
362        (
363                const   XMLCh* const    name
364        ) = 0 ;
365
366    //@}
367private :
368    /* Unimplemented Constructors and operators */
369    /* Copy constructor */
370    ContentHandler(const ContentHandler&);
371    /** Assignment operator */
372    ContentHandler& operator=(const ContentHandler&);
373};
374
375XERCES_CPP_NAMESPACE_END
376
377#endif
Note: See TracBrowser for help on using the repository browser.