nlib
nn::nlib::exi::XmlStreamWriter Class Referenceabstract

Abstract class that writes to an XML stream. More...

#include "nn/nlib/exi/XmlStreamWriter.h"

Public Member Functions

void Flush () noexcept
 Flushes the XML writer cache. More...
 
void WriteCData (const ExiChar *data) noexcept
 Writes the text specified as an argument. More...
 
void WriteCharacters (const ExiChar *text) noexcept
 Writes the text specified as an argument. More...
 
void WriteComment (const ExiChar *data) noexcept
 Writes the XML comment (<!--...-->) containing text that was specified as an argument. More...
 
void WriteProcessingInstruction (const ExiChar *target, const ExiChar *data) noexcept
 Writes a PI (processing instruction) like <?target data?>. More...
 
Writing XML Namespaces
const ExiCharGetPrefix (const ExiChar *uri) noexcept
 Gets the prefix corresponding to the namespace URI. More...
 
void WriteNamespace (const ExiChar *prefix, const ExiChar *namespace_uri) noexcept
 Declares the XML namespace. More...
 
void WriteDefaultNamespace (const ExiChar *namespace_uri) noexcept
 Declares the default namespace. More...
 
Writing XML Attributes
void WriteAttribute (const ExiChar *local_name, const ExiChar *value) noexcept
 Writes an attribute and value without a namespace. More...
 
void WriteAttribute (const ExiChar *prefix, const ExiChar *namespace_uri, const ExiChar *local_name, const ExiChar *value) noexcept
 Writes an attribute and value with a namespace. More...
 
Writing Opening and Closing Tags
void WriteEmptyElement (const ExiChar *local_name) noexcept
 Writes opening tags and closing tags for elements without a namespace. More...
 
void WriteEmptyElement (const ExiChar *prefix, const ExiChar *namespace_uri, const ExiChar *local_name) noexcept
 Writes opening tags and closing tags for elements with a namespace. More...
 
void WriteEndElement () noexcept
 Writes a closing tag.
 
void WriteStartElement (const ExiChar *local_name) noexcept
 Writes an opening tag of an element without a namespace. More...
 
void WriteStartElement (const ExiChar *prefix, const ExiChar *namespace_uri, const ExiChar *local_name) noexcept
 Writes an opening tag of an element with a namespace. More...
 
Starting and Ending XML Documents
void WriteStartDocument () noexcept
 Declares the start of an XML document and writes data including the XML declaration.
 
void WriteEndDocument () noexcept
 Closes all open elements and closes the XML writer.
 
Error Checking
bool IsError () const noexcept
 Returns true if an error has occurred.
 
bool IsOk () const noexcept
 Returns true if an error has not occurred.
 
ExiErrorStatus::ErrorValue GetError () const noexcept
 Gets the error value.
 
ExiErrorStatusGetErrorStatus () const noexcept
 Gets an error status object.
 
 operator bool () const
 Returns true if an error has not occurred.
 

XmlStreamWriter Object Initialization and Finalization

Instantiates an object using a static member function.

The XmlStreamWriter constructor has not been made public. You must call the Create function. Objects created using the Create function can be deleted (using delete), but normally this is handled using UniquePtr.

static XmlStreamWriterCreate (OutputStream *stream, const XmlStreamWriterSettings &settings, const ExiAllocatorEx &al) noexcept
 Creates an XmlStreamWriter instance by specifying an objectwise allocator. More...
 
static XmlStreamWriterCreate (OutputStream *stream, const XmlStreamWriterSettings &settings) noexcept
 Creates an instance of XmlStreamWriter. More...
 
static XmlStreamWriterCreate (OutputStream *stream) noexcept
 Creates an XmlStreamWriter instance using default settings for XmlStreamWriterSettings. More...
 
static XmlStreamWriterCreate (OutputStream *stream, const ExiAllocatorEx &al) noexcept
 Creates an XmlStreamWriter instance by specifying an objectwise allocator. More...
 
void Close () noexcept
 Closes an XmlStreamWriter. The original stream is not actually closed; it merely is detached.
 

Detailed Description

Abstract class that writes to an XML stream.

Description
This class allows you to write XML using code similar to the XMLStreamWriter class in Java StAX or .NET's XmlWriter class.
Use XmlStreamWriter::Create() to create a new XmlStreamWriter instance. The instance is created by obtaining memory from ExiAllocator.
Typically, XML is written using code like the following.
if (!w.get()) {
// Failed to generate an instance.
// Memory allocation from ExiAllocator may have failed.
return out_of_memory;
}
w->WriteStartDocument();
w->WriteStartElement(...);
// ....
w->WriteEndElement();
w->WriteEndDocument();
w->Flush();
if (w->IsError()) {
// An error occurred during the operation.
// After an error occurs, nothing happens even if you make calls to the XmlStreamWriter API.
// Any crashes or other glitches that occur here are bugs in the exi library.
return error;
}
return ok;

Definition at line 41 of file XmlStreamWriter.h.

Member Function Documentation

nn::nlib::exi::XmlStreamWriter::Create ( OutputStream stream,
const XmlStreamWriterSettings settings,
const ExiAllocatorEx al 
)
staticnoexcept

Creates an XmlStreamWriter instance by specifying an objectwise allocator.

Parameters
[in]streamOriginal output stream.
[in]settingsConfiguration options.
[in]alAllocator.
Returns
Returns the XmlStreamWriter instance that was created.
nn::nlib::exi::XmlStreamWriter::Create ( OutputStream stream,
const XmlStreamWriterSettings settings 
)
inlinestaticnoexcept

Creates an instance of XmlStreamWriter.

Parameters
[in]streamOriginal output stream.
[in]settingsConfiguration options.
Returns
Returns the XmlStreamWriter instance that was created.
Description
The instance is created by obtaining memory from ExiAllocator. If successful, it returns a non-NULL pointer. Generally, the pointer that is returned is stored and used via UniquePtr.
If you want to preserve prefix names or write XML comments, you must specify non-default options for XmlStreamWriterSettings. For more information, see XmlStreamWriterSettings.

Definition at line 45 of file XmlStreamWriter.h.

nn::nlib::exi::XmlStreamWriter::Create ( OutputStream stream)
inlinestaticnoexcept

Creates an XmlStreamWriter instance using default settings for XmlStreamWriterSettings.

Parameters
[in]streamOriginal output stream.
Returns
Returns the XmlStreamWriter instance that was created.
Description
This is equivalent to the code below.
nn::nlib::exi::OutputStream* stream = ....;

Definition at line 50 of file XmlStreamWriter.h.

nn::nlib::exi::XmlStreamWriter::Create ( OutputStream stream,
const ExiAllocatorEx al 
)
inlinestaticnoexcept

Creates an XmlStreamWriter instance by specifying an objectwise allocator.

Parameters
[in]streamOriginal output stream.
[in]alAllocator.
Returns
Returns the XmlStreamWriter instance that was created.

Definition at line 54 of file XmlStreamWriter.h.

nn::nlib::exi::XmlStreamWriter::Flush ( )
inlinenoexcept

Flushes the XML writer cache.

Description
Flushes the data in the original stream, in addition to the original stream itself.

Definition at line 65 of file XmlStreamWriter.h.

nn::nlib::exi::XmlStreamWriter::GetPrefix ( const ExiChar uri)
inlinenoexcept

Gets the prefix corresponding to the namespace URI.

Parameters
[in]uriSpecifies the namespace URI.
Returns
Returns the namespace prefix.
Description
Returns NULL if there is no namespace, or an empty string if the namespace is the default namespace. Specifying NULL for uri is treated as an empty string.
Returns a string representing the corresponding prefix if the namespace contains multiple prefixes.

Definition at line 69 of file XmlStreamWriter.h.

nn::nlib::exi::XmlStreamWriter::WriteAttribute ( const ExiChar local_name,
const ExiChar value 
)
inlinenoexcept

Writes an attribute and value without a namespace.

Parameters
[in]local_nameSpecifies the local attribute name.
[in]valueSpecifies the attribute value.
Description
This is equivalent to the code below.
WriteAttribute(L"", L"", local_name, value);

Definition at line 73 of file XmlStreamWriter.h.

nn::nlib::exi::XmlStreamWriter::WriteAttribute ( const ExiChar prefix,
const ExiChar namespace_uri,
const ExiChar local_name,
const ExiChar value 
)
noexcept

Writes an attribute and value with a namespace.

Parameters
[in]prefixSpecifies the namespace prefix of the attribute.
[in]namespace_uriSpecifies the namespace URI of the attribute.
[in]local_nameSpecifies the local attribute name.
[in]valueSpecifies the attribute value.
Description
Neither NULL nor an empty string can be passed to the localName parameter. Specifying NULL is treated as an empty string in the prefix parameter, namespaceUri parameter, and value parameter.
nn::nlib::exi::XmlStreamWriter::WriteCData ( const ExiChar data)
inlinenoexcept

Writes the text specified as an argument.

Parameters
[in]dataSpecifies the text to write.
Description
Specifying NULL for data is treated as an empty string.

Definition at line 78 of file XmlStreamWriter.h.

nn::nlib::exi::XmlStreamWriter::WriteCharacters ( const ExiChar text)
inlinenoexcept

Writes the text specified as an argument.

Parameters
[in]textSpecifies the text to write.
Description
Specifying NULL for text is treated as an empty string.

Definition at line 83 of file XmlStreamWriter.h.

nn::nlib::exi::XmlStreamWriter::WriteComment ( const ExiChar data)
noexcept

Writes the XML comment (<!--...-->) containing text that was specified as an argument.

Parameters
[in]dataSpecifies the text within the XML comment.
Description
Specifying NULL for data is treated as an empty string.
nn::nlib::exi::XmlStreamWriter::WriteDefaultNamespace ( const ExiChar namespace_uri)
inlinenoexcept

Declares the default namespace.

Parameters
[in]namespace_uriSpecifies the namespace URI of the default namespace.
Description
This function is equivalent to the code below.
WriteNamespace(L"", namespace_uri);

Definition at line 96 of file XmlStreamWriter.h.

nn::nlib::exi::XmlStreamWriter::WriteEmptyElement ( const ExiChar local_name)
inlinenoexcept

Writes opening tags and closing tags for elements without a namespace.

Parameters
[in]local_nameSpecifies the local element name.
Description
This function is equivalent to the code below.
WriteEmptyElement(L"", L"", local_name);

Definition at line 100 of file XmlStreamWriter.h.

nn::nlib::exi::XmlStreamWriter::WriteEmptyElement ( const ExiChar prefix,
const ExiChar namespace_uri,
const ExiChar local_name 
)
noexcept

Writes opening tags and closing tags for elements with a namespace.

Parameters
[in]prefixSpecifies the namespace prefix of the element.
[in]namespace_uriSpecifies the namespace URI of the element.
[in]local_nameSpecifies the local element name.
Description
This function is equivalent to the code below.
WriteStartElement(prefix, namespace_uri, local_name);
nn::nlib::exi::XmlStreamWriter::WriteNamespace ( const ExiChar prefix,
const ExiChar namespace_uri 
)
inlinenoexcept

Declares the XML namespace.

Parameters
[in]prefixSpecifies the prefix corresponding to the namespace.
[in]namespace_uriSpecifies the namespace URI.
Description
Specifying NULL for prefix or namespaceUri is treated as an empty string.

Definition at line 90 of file XmlStreamWriter.h.

nn::nlib::exi::XmlStreamWriter::WriteProcessingInstruction ( const ExiChar target,
const ExiChar data 
)
noexcept

Writes a PI (processing instruction) like <?target data?>.

Parameters
[in]targetSpecifies the name of the PI.
[in]dataSpecifies the text to include in the PI.
Description
To write PI, XmlStreamWriter must be created with Preserve::pis set to true. Otherwise, nothing is written even if you call this function.
XML declarations cannot be written using this function. Use WriteStartDocument.
NeitherNULL nor an empty string can be passed to the target parameter. Specifying NULL for data is treated as an empty string.
nn::nlib::exi::XmlStreamWriter::WriteStartElement ( const ExiChar local_name)
inlinenoexcept

Writes an opening tag of an element without a namespace.

Parameters
[in]local_nameSpecifies the local element name.
Description
This is equivalent to the code below.
WriteStartElement(L"", L"", local_name);

Definition at line 123 of file XmlStreamWriter.h.

nn::nlib::exi::XmlStreamWriter::WriteStartElement ( const ExiChar prefix,
const ExiChar namespace_uri,
const ExiChar local_name 
)
noexcept

Writes an opening tag of an element with a namespace.

Parameters
[in]prefixSpecifies the namespace prefix of the element.
[in]namespace_uriSpecifies the namespace URI of the element.
[in]local_nameSpecifies the local element name.
Description
If the prefix is not associated with a namespace URI, the corresponding namespace declaration is output.
If using the default namespace, call this function and specify either NULL or an empty string for the prefix parameter.
WriteStartElement(L"", uri, local_name); // <localName xmlns="uri">
In this case, the default namespace is declared even if a prefix was already provided for the namespace URI.
You cannot omit the namespace URI, even if you are only specifying the prefix.

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