libxml++  2.36.0
Classes | Public Types | Public Member Functions | Protected Member Functions | List of all members
xmlpp::SaxParser Class Reference

SAX XML parser. More...

#include <libxml++/parsers/saxparser.h>

Inheritance diagram for xmlpp::SaxParser:
Inheritance graph
[legend]
Collaboration diagram for xmlpp::SaxParser:
Collaboration graph
[legend]

Classes

struct  Attribute
 Simple structure used in the start_element callback, in which the attributes are a list of name/value pairs. More...
struct  AttributeHasName
 This functor is a helper to find an attribute by name in an AttributeList using the standard algorithm std::find_if. More...

Public Types

typedef std::deque< AttributeAttributeList
- Public Types inherited from xmlpp::Parser
typedef unsigned int size_type

Public Member Functions

 SaxParser (bool use_get_entity=false)
virtual ~SaxParser ()
virtual void parse_file (const Glib::ustring& filename)
 Parse an XML document from a file.
virtual void parse_memory (const Glib::ustring& contents)
 Parse an XML document from a string.
void parse_memory_raw (const unsigned char* contents, size_type bytes_count)
 Parse an XML document from raw memory.
virtual void parse_stream (std::istream& in)
 Parse an XML document from a stream.
virtual void parse_chunk (const Glib::ustring& chunk)
 Parse a chunk of data.
void parse_chunk_raw (const unsigned char* contents, size_type bytes_count)
 Parse a chunk of data.
virtual void finish_chunk_parsing ()
 Finish a chunk-wise parse.
- Public Member Functions inherited from xmlpp::Parser
 Parser ()
virtual ~Parser ()
virtual void set_validate (bool val=true)
 By default, the parser will not validate the XML file.
virtual bool get_validate () const
 See set_validate()
virtual void set_substitute_entities (bool val=true)
 Set whether the parser will automatically substitute entity references with the text of the entities' definitions.
virtual bool get_substitute_entities () const
 See set_substitute_entities().
void set_throw_messages (bool val=true)
 Set whether the parser will collect and throw error and warning messages.
bool get_throw_messages () const
 See set_throw_messages().

Protected Member Functions

virtual void on_start_document ()
virtual void on_end_document ()
virtual void on_start_element (const Glib::ustring& name, const AttributeList& attributes)
virtual void on_end_element (const Glib::ustring& name)
virtual void on_characters (const Glib::ustring& characters)
virtual void on_comment (const Glib::ustring& text)
virtual void on_warning (const Glib::ustring& text)
virtual void on_error (const Glib::ustring& text)
virtual void on_fatal_error (const Glib::ustring& text)
virtual void on_cdata_block (const Glib::ustring& text)
virtual void on_internal_subset (const Glib::ustring& name, const Glib::ustring& publicId, const Glib::ustring& systemId)
 Override this to receive information about the document's DTD and any entity declarations.
virtual _xmlEntity* on_get_entity (const Glib::ustring& name)
 Override this method to resolve entities references in your derived parser, instead of using the default entity resolution, or to be informed when entity references are encountered.
virtual void on_entity_declaration (const Glib::ustring& name, XmlEntityType type, const Glib::ustring& publicId, const Glib::ustring& systemId, const Glib::ustring& content)
 Override this to receive information about every entity declaration.
virtual void release_underlying ()
- Protected Member Functions inherited from xmlpp::Parser
virtual void initialize_context ()
virtual void on_validity_error (const Glib::ustring& message)
virtual void on_validity_warning (const Glib::ustring& message)
virtual void handleException (const exception& e)
virtual void check_for_exception ()
virtual void check_for_validity_messages ()

Additional Inherited Members

- Protected Types inherited from xmlpp::Parser
enum  MsgType {
  MsgParserError,
  MsgParserWarning,
  MsgValidityError,
  MsgValidityWarning
}
- Static Protected Member Functions inherited from xmlpp::Parser
static void callback_parser_error (void* ctx, const char* msg,...)
static void callback_parser_warning (void* ctx, const char* msg,...)
static void callback_validity_error (void* ctx, const char* msg,...)
static void callback_validity_warning (void* ctx, const char* msg,...)
static void callback_error_or_warning (MsgType msg_type, void* ctx, const char* msg, va_list var_args)
- Protected Attributes inherited from xmlpp::Parser
_xmlParserCtxt* context_
exceptionexception_
Glib::ustring validate_error_
Glib::ustring validate_warning_
bool validate_
bool substitute_entities_

Detailed Description

SAX XML parser.

Derive your own class and override the on_*() methods.

Member Typedef Documentation

Constructor & Destructor Documentation

xmlpp::SaxParser::SaxParser ( bool  use_get_entity = false)
Parameters
use_get_entitySet this to true if you will override on_get_entity(). In theory, if you do not override on_get_entity() the parser should behave exactly the same whether you use true or false here. But the default implementation of on_get_entity(), needed if you override on_get_entity() might not have the same behaviour as the underlying default behaviour of libxml, so the libxml implementation is the default here.
virtual xmlpp::SaxParser::~SaxParser ( )
virtual

Member Function Documentation

virtual void xmlpp::SaxParser::finish_chunk_parsing ( )
virtual

Finish a chunk-wise parse.

Call this after the last call to parse_chunk(). Don't use this function with the other parsing methods.

Exceptions
xmlpp::internal_error
xmlpp::parse_error
xmlpp::validity_error
virtual void xmlpp::SaxParser::on_cdata_block ( const Glib::ustring &  text)
protectedvirtual
virtual void xmlpp::SaxParser::on_characters ( const Glib::ustring &  characters)
protectedvirtual
virtual void xmlpp::SaxParser::on_comment ( const Glib::ustring &  text)
protectedvirtual
virtual void xmlpp::SaxParser::on_end_document ( )
protectedvirtual
virtual void xmlpp::SaxParser::on_end_element ( const Glib::ustring &  name)
protectedvirtual
virtual void xmlpp::SaxParser::on_entity_declaration ( const Glib::ustring &  name,
XmlEntityType  type,
const Glib::ustring &  publicId,
const Glib::ustring &  systemId,
const Glib::ustring &  content 
)
protectedvirtual

Override this to receive information about every entity declaration.

If you override this function, and you want normal entity substitution to work, then you must call the base class in your override.

This would be useful when overriding on_get_entity().

Exceptions
xmlpp::internal_error
virtual void xmlpp::SaxParser::on_error ( const Glib::ustring &  text)
protectedvirtual
virtual void xmlpp::SaxParser::on_fatal_error ( const Glib::ustring &  text)
protectedvirtual
Exceptions
xmlpp::parse_error
virtual _xmlEntity* xmlpp::SaxParser::on_get_entity ( const Glib::ustring &  name)
protectedvirtual

Override this method to resolve entities references in your derived parser, instead of using the default entity resolution, or to be informed when entity references are encountered.

If you override this function then you must also specify true for use_get_entity constructor parameter. You will probably need to override on_entity_declaration() as well so that you can use that information when resolving the entity reference.

This is known to be difficult, because it requires both an understanding of the W3C specifications and knowledge of the libxml internals. Entity resolution is easier with the DomParser.

Call this method in this base class for default processing. For instance, if you just want to know about the existence of an entity reference, without affecting the normal substitution, just override and call the base class.

Unlike the DomParser, the SaxParser will also tell you about entity references for the 5 predefined entities.

Parameters
nameThe entity reference name.
Returns
The resolved xmlEntity for the entity reference, or 0 if not found. You must include libxml/parser.h in order to use this C struct. This instance will not be freed by the caller.
virtual void xmlpp::SaxParser::on_internal_subset ( const Glib::ustring &  name,
const Glib::ustring &  publicId,
const Glib::ustring &  systemId 
)
protectedvirtual

Override this to receive information about the document's DTD and any entity declarations.

virtual void xmlpp::SaxParser::on_start_document ( )
protectedvirtual
virtual void xmlpp::SaxParser::on_start_element ( const Glib::ustring &  name,
const AttributeList attributes 
)
protectedvirtual
virtual void xmlpp::SaxParser::on_warning ( const Glib::ustring &  text)
protectedvirtual
virtual void xmlpp::SaxParser::parse_chunk ( const Glib::ustring &  chunk)
virtual

Parse a chunk of data.

This lets you pass a document in small chunks, e.g. from a network connection. The on_* virtual functions are called each time the chunks provide enough information to advance the parser.

The first call to parse_chunk will setup the parser. When the last chunk has been parsed, call finish_chunk_parsing() to finish the parse.

Parameters
chunkThe next piece of the XML document.
Exceptions
xmlpp::internal_error
xmlpp::parse_error
xmlpp::validity_error
void xmlpp::SaxParser::parse_chunk_raw ( const unsigned char *  contents,
size_type  bytes_count 
)

Parse a chunk of data.

Since libxml++ 2.24:

This lets you pass a document in small chunks, e.g. from a network connection. The on_* virtual functions are called each time the chunks provide enough information to advance the parser.

The first call to parse_chunk will setup the parser. When the last chunk has been parsed, call finish_chunk_parsing() to finish the parse.

Parameters
contentsThe next piece of the XML document as an array of bytes.
bytes_countThe number of bytes in the contents array.
Exceptions
xmlpp::internal_error
xmlpp::parse_error
xmlpp::validity_error
virtual void xmlpp::SaxParser::parse_file ( const Glib::ustring &  filename)
virtual

Parse an XML document from a file.

Parameters
filenameThe path to the file.
Exceptions
xmlpp::internal_error
xmlpp::parse_error
xmlpp::validity_error

Implements xmlpp::Parser.

virtual void xmlpp::SaxParser::parse_memory ( const Glib::ustring &  contents)
virtual

Parse an XML document from a string.

Parameters
contentsThe XML document as a string.
Exceptions
xmlpp::internal_error
xmlpp::parse_error
xmlpp::validity_error

Implements xmlpp::Parser.

void xmlpp::SaxParser::parse_memory_raw ( const unsigned char *  contents,
size_type  bytes_count 
)

Parse an XML document from raw memory.

Parameters
contentsThe XML document as an array of bytes.
bytes_countThe number of bytes in the contents array.
Exceptions
xmlpp::internal_error
xmlpp::parse_error
xmlpp::validity_error
virtual void xmlpp::SaxParser::parse_stream ( std::istream &  in)
virtual

Parse an XML document from a stream.

Parameters
inThe stream.
Exceptions
xmlpp::internal_error
xmlpp::parse_error
xmlpp::validity_error

Implements xmlpp::Parser.

virtual void xmlpp::SaxParser::release_underlying ( )
protectedvirtual

Reimplemented from xmlpp::Parser.


The documentation for this class was generated from the following file: