Library: XML
Package: XML
Header: Poco/XML/XMLWriter.h
This class serializes SAX2 ContentHandler, LexicalHandler and DTDHandler events back into a stream.
Various consistency checks are performed on the written data (i.e. there must be exactly one root element and every startElement() must have a matching endElement()).
The XMLWriter supports optional pretty-printing of the serialized XML. Note, however, that pretty-printing XML data alters the information set of the document being written, since in XML all whitespace is potentially relevant to an application.
The writer contains extensive support for XML Namespaces, so that a client application does not have to keep track of prefixes and supply xmlns attributes.
If the client does not provide namespace prefixes (either by specifying them as part of the qualified name given to startElement(), or by calling startPrefixMapping()), the XMLWriter automatically generates namespace prefixes in the form ns1, ns2, etc.
Direct Base Classes: ContentHandler, LexicalHandler, DTDHandler
All Base Classes: ContentHandler, DTDHandler, LexicalHandler
Member Functions: addAttributes, addNamespaceAttributes, characters, closeStartTag, comment, dataElement, declareAttributeNamespaces, emptyElement, endCDATA, endDTD, endDocument, endElement, endEntity, endFragment, endPrefixMapping, getIndent, getNewLine, ignorableWhitespace, nameToString, newPrefix, notationDecl, prettyPrint, processingInstruction, rawCharacters, setDocumentLocator, setIndent, setNewLine, skippedEntity, startCDATA, startDTD, startDocument, startElement, startEntity, startFragment, startPrefixMapping, unparsedEntityDecl, writeAttributes, writeEndElement, writeIndent, writeMarkup, writeName, writeNewLine, writeStartElement, writeXML, writeXMLDeclaration
Inherited Functions: characters, comment, endCDATA, endDTD, endDocument, endElement, endEntity, endPrefixMapping, ignorableWhitespace, notationDecl, processingInstruction, setDocumentLocator, skippedEntity, startCDATA, startDTD, startDocument, startElement, startEntity, startPrefixMapping, unparsedEntityDecl
typedef std::map < XMLString, XMLString > AttributeMap;
CANONICAL = 0x00
Do not write an XML declaration (default).
CANONICAL_XML = 0x01
Enables basic support for Canonical XML:
WRITE_XML_DECLARATION = 0x02
Write an XML declaration.
PRETTY_PRINT = 0x04
Pretty-print XML markup.
PRETTY_PRINT_ATTRIBUTES = 0x08
Write each attribute on a separate line. PRETTY_PRINT must be specified as well.
XMLWriter(
XMLByteOutputStream & str,
int options
);
Creates the XMLWriter and sets the specified options.
The resulting stream will be UTF-8 encoded.
XMLWriter(
XMLByteOutputStream & str,
int options,
const std::string & encodingName,
Poco::TextEncoding & textEncoding
);
Creates the XMLWriter and sets the specified options.
The encoding is reflected in the XML declaration. The caller is responsible for that the given encodingName matches with the given textEncoding.
XMLWriter(
XMLByteOutputStream & str,
int options,
const std::string & encodingName,
Poco::TextEncoding * pTextEncoding
);
Creates the XMLWriter and sets the specified options.
The encoding is reflected in the XML declaration. The caller is responsible for that the given encodingName matches with the given textEncoding. If pTextEncoding is null, the given encodingName is ignored and the default UTF-8 encoding is used.
~XMLWriter();
Destroys the XMLWriter.
void characters(
const XMLChar ch[],
int start,
int length
);
Writes XML character data. Quotes, ampersand's, less-than and greater-than signs are escaped, unless a CDATA section has been opened by calling startCDATA().
The characters must be encoded in UTF-8 (if XMLChar is char) or UTF-16 (if XMLChar is wchar_t).
See also: Poco::XML::ContentHandler::characters()
void characters(
const XMLString & str
);
Writes XML character data. Quotes, ampersand's, less-than and greater-than signs are escaped, unless a CDATA section has been opened by calling startCDATA().
The characters must be encoded in UTF-8 (if XMLChar is char) or UTF-16 (if XMLChar is wchar_t).
void comment(
const XMLChar ch[],
int start,
int length
);
Writes a comment.
See also: Poco::XML::LexicalHandler::comment()
void dataElement(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname,
const XMLString & data,
const XMLString & attr1 = XMLString (),
const XMLString & value1 = XMLString (),
const XMLString & attr2 = XMLString (),
const XMLString & value2 = XMLString (),
const XMLString & attr3 = XMLString (),
const XMLString & value3 = XMLString ()
);
Writes a data element in the form <name attr1="value1"...>data</name>.
void emptyElement(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname
);
Writes an empty XML element tag (<elem/>).
void emptyElement(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname,
const Attributes & attributes
);
Writes an empty XML element tag with the given attributes (<elem attr1="value1"... />).
void endCDATA();
Writes the ] string that ends a CDATA section.
See also: Poco::XML::LexicalHandler::endCDATA()
void endDTD();
Writes the closing characters of a DTD declaration.
See also: Poco::XML::LexicalHandler::endDTD()
void endDocument();
Checks that all elements are closed and prints a final newline.
See also: Poco::XML::ContentHandler::endDocument()
void endElement(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname
);
Writes an XML end element tag.
Throws an exception if the name of doesn't match the one of the most recent startElement().
See also: Poco::XML::ContentHandler::endElement()
void endEntity(
const XMLString & name
);
Does nothing.
See also: Poco::XML::LexicalHandler::endEntity()
void endFragment();
Checks that all elements are closed and prints a final newline.
void endPrefixMapping(
const XMLString & prefix
);
End the scope of a prefix-URI mapping.
const std::string & getIndent() const;
Returns the string used for one indentation step.
const std::string & getNewLine() const;
Returns the line ending currently in use.
void ignorableWhitespace(
const XMLChar ch[],
int start,
int length
);
Writes whitespace characters by simply passing them to characters().
void notationDecl(
const XMLString & name,
const XMLString * publicId,
const XMLString * systemId
);
See also: Poco::XML::DTDHandler::notationDecl()
void processingInstruction(
const XMLString & target,
const XMLString & data
);
Writes a processing instruction.
void rawCharacters(
const XMLString & str
);
Writes the characters in the given string as they are. The caller is responsible for escaping characters as necessary to produce valid XML.
The characters must be encoded in UTF-8 (if XMLChar is char) or UTF-16 (if XMLChar is wchar_t).
void setDocumentLocator(
const Locator * loc
);
Currently unused.
void setIndent(
const std::string & indent
);
Sets the string used for one indentation step.
The default is a single TAB character. The given string should only contain TAB or SPACE characters (e.g., a single TAB character, or two to four SPACE characters).
void setNewLine(
const std::string & newLineCharacters
);
Sets the line ending for the resulting XML file.
Possible values are:
void skippedEntity(
const XMLString & name
);
Does nothing.
void startCDATA();
Writes the [CDATA[ string that begins a CDATA section. Use characters() to write the actual character data.
See also: Poco::XML::LexicalHandler::startCDATA()
void startDTD(
const XMLString & name,
const XMLString & publicId,
const XMLString & systemId
);
Writes a DTD declaration.
See also: Poco::XML::LexicalHandler::startDTD()
void startDocument();
Writes a generic XML declaration to the stream. If a document type has been set (see SetDocumentType), a DOCTYPE declaration is also written.
void startElement(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname,
const Attributes & attributes
);
Writes an XML start element tag.
Namespaces are handled as follows.
void startElement(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname
);
Writes an XML start element tag with no attributes. See the other startElement() method for more information.
void startEntity(
const XMLString & name
);
Does nothing.
See also: Poco::XML::LexicalHandler::startEntity()
void startFragment();
Use this instead of StartDocument() if you want to write a fragment rather than a document (no XML declaration and more than one "root" element allowed).
void startPrefixMapping(
const XMLString & prefix,
const XMLString & namespaceURI
);
Begin the scope of a prefix-URI Namespace mapping. A namespace declaration is written with the next element.
void unparsedEntityDecl(
const XMLString & name,
const XMLString * publicId,
const XMLString & systemId,
const XMLString & notationName
);
void addAttributes(
AttributeMap & attributeMap,
const Attributes & attributes,
const XMLString & elementNamespaceURI
);
void addNamespaceAttributes(
AttributeMap & attributeMap
);
void closeStartTag();
void declareAttributeNamespaces(
const Attributes & attributes
);
static std::string nameToString(
const XMLString & localName,
const XMLString & qname
);
XMLString newPrefix();
void prettyPrint() const;
void writeAttributes(
const AttributeMap & attributeMap
);
void writeEndElement(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname
);
void writeIndent() const;
void writeIndent(
int indent
) const;
void writeMarkup(
const std::string & str
) const;
void writeName(
const XMLString & prefix,
const XMLString & localName
);
void writeNewLine() const;
void writeStartElement(
const XMLString & namespaceURI,
const XMLString & localName,
const XMLString & qname,
const Attributes & attributes
);
void writeXML(
const XMLString & str
) const;
void writeXML(
XMLChar ch
) const;
void writeXMLDeclaration();
static const std::string NEWLINE_CR;
static const std::string NEWLINE_CRLF;
static const std::string NEWLINE_DEFAULT;
static const std::string NEWLINE_LF;