FDO .NET API Reference Feature Data Objects
Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

OSGeo::FDO::Common::Xml::XmlWriter Class Reference

Inherits OSGeo::FDO::Runtime::Disposable.

Inheritance diagram for OSGeo::FDO::Common::Xml::XmlWriter:

[legend]
List of all members.

Detailed Description

XmlWriter writes an XML document to a text or binary stream. Note: The XML document is not completely written until this object is destroyed by releasing all references to it. Therefore, this object must be destroyed before reading back the document being written.


Public Types

enum  LineFormat {
  LineFormat_None = FdoXmlWriter::LineFormat_None,
  LineFormat_Break = FdoXmlWriter::LineFormat_Break,
  LineFormat_Indent = FdoXmlWriter::LineFormat_Indent
}
 XmlWriter::LineFormat specifies whether the output XML document has line breaks or indentation. More...

Public Member Functions

System::Void Close ()
 Closes this XML Writer by writing end tags for all elements currently open. Once this function is called, no more elements can be added to the output document.
System::String * EncodeName (System::String *name)
 utility function that converts FDO element names to valid XML element or attribute names. Conversion is done by changing each invalid character to a hex pattern ( "-xnnnn-" ).
__property System::Boolean get_DefaultRoot ()
 Gets the current default root state.
__property OSGeo::FDO::Common::Io::IoStreamget_Stream ()
 Gets the underlying stream. If a text writer was passed to this object then the stream for this text writer is returned. If a stream was passed to this object then this stream is returned. If a file name as passed then a auto-generated stream (wrapped around the file) is returned.
__property OSGeo::FDO::Common::Io::IoTextWriterget_TextWriter ()
 Gets the underlying text writer. If a text writer was passed to this object then this text writeer is returned. Otherwise, an auto-generated text writer is returned (a text writer wrapped around the file name or stream that was passed to this object).
System::Boolean IsValidName (System::String *name)
 Checks if a string is a valid XML 1.0 element or attribute name.
__property System::Void set_DefaultRoot (System::Boolean defaultRoot)
 Sets whether to write the default root element. Must be called before the first element is written, otherwise an exception is thrown.
System::String * UriToQName (System::String *location, System::String *localName)
System::String * UriToQName (System::String *location, System::String *localName, System::Boolean isElement)
 Given an element's or attribute's globally unique name ( uri and local name ), this function returns its fully qualified name as per the XML document being written, or the unqualified name if the uri is the default namespace. This is done by searching for the current namespace declaration that references the uri.
System::Void WriteAttribute (System::String *attributeName, System::String *attributeValue)
 Writes an attribute to the current element. An Exception is thrown if this function is called immediately after WriteEndElement().
System::Void WriteBytes (System::Byte bytes[], System::UInt32 count)
 Writes arbitrary bytes to the XML Writer. Caller is responsible for ensuring that the text does not introduce any errors into the XML document.
System::Void WriteCharacters (System::String *characters)
 Writes simple (character) content for the current element. This function can be called multiple times for the same element. The characters are appended to the element's content. An Exception is thrown if there is no current element.
System::Void WriteEndElement ()
 Writes the end tag for the current element to the document. An Exception is thrown if there is no element to end.
System::Void WriteStartElement (System::String *elementName)
 Writes an element start tag to the document.
 XmlWriter (OSGeo::FDO::Common::Io::IoTextWriter *writer)
 Constructs an XML writer on a text writer.
 XmlWriter (OSGeo::FDO::Common::Io::IoTextWriter *writer, System::Boolean defaultRoot)
 Constructs an XML writer on a text writer.
 XmlWriter (OSGeo::FDO::Common::Io::IoTextWriter *writer, System::Boolean defaultRoot, OSGeo::FDO::Common::Xml::XmlWriter::LineFormat lineFormat)
 Constructs an XML writer on a text writer.
 XmlWriter (OSGeo::FDO::Common::Io::IoTextWriter *writer, System::Boolean defaultRoot, OSGeo::FDO::Common::Xml::XmlWriter::LineFormat lineFormat, System::UInt32 lineLength)
 Constructs an XML writer on a text writer.
 XmlWriter (OSGeo::FDO::Common::Io::IoStream *stream)
 Constructs an XML writer on a stream.
 XmlWriter (OSGeo::FDO::Common::Io::IoStream *stream, System::Boolean defaultRoot)
 Constructs an XML writer on a stream.
 XmlWriter (OSGeo::FDO::Common::Io::IoStream *stream, System::Boolean defaultRoot, OSGeo::FDO::Common::Xml::XmlWriter::LineFormat lineFormat)
 Constructs an XML writer on a stream.
 XmlWriter (OSGeo::FDO::Common::Io::IoStream *stream, System::Boolean defaultRoot, OSGeo::FDO::Common::Xml::XmlWriter::LineFormat lineFormat, System::UInt32 lineLength)
 Constructs an XML writer on a stream.
 XmlWriter (System::String *fileName)
 Constructs an XML writer on a file.
 XmlWriter (System::String *fileName, System::Boolean defaultRoot)
 Constructs an XML writer on a file.
 XmlWriter (System::String *fileName, System::Boolean defaultRoot, OSGeo::FDO::Common::Xml::XmlWriter::LineFormat lineFormat)
 Constructs an XML writer on a file.
 XmlWriter (System::String *fileName, System::Boolean defaultRoot, OSGeo::FDO::Common::Xml::XmlWriter::LineFormat lineFormat, System::UInt32 lineLength)
 Constructs an XML writer on a file.

Protected Member Functions

System::Void ReleaseUnmanagedObject ()
 DOXYGEN-IGNORE

Member Enumeration Documentation

enum OSGeo::FDO::Common::Xml::XmlWriter::LineFormat
 

XmlWriter::LineFormat specifies whether the output XML document has line breaks or indentation.

Parameters:
LineFormat_None The document is written without line breaks or element indentation.
LineFormat_Break The document is written with a line break after:
  • every end element tag
  • every start tag for elements with complex content (sub-elements)
Elements are not indented.
LineFormat_Indent Same as LineFormat_Break, except that each element immediately following a line break is indented by a certain number of spaces. The number of spaces is the element's nesting level within the document X 3. The root element has nesting level 0.
Enumeration values:
LineFormat_None 
LineFormat_Break 
LineFormat_Indent 

Constructor & Destructor Documentation

OSGeo::FDO::Common::Xml::XmlWriter::XmlWriter System::String *  fileName,
System::Boolean  defaultRoot,
OSGeo::FDO::Common::Xml::XmlWriter::LineFormat  lineFormat,
System::UInt32  lineLength
 

Constructs an XML writer on a file.

Parameters:
fileName Input name of the file to write.
defaultRoot true: all elements written are wrapped in a default root element, named "DataStore". false: the default root element is not written. In this case, the first element written (via WriteStartElement() ) becomes the root element. The caller is responsible for ensuring that only one root element is written (the XML standard disallows multiple root elements).
lineFormat Input indentation string for XML elements. If NULL the XML document contains no line breaks and elements are not indented. if L"" then the XML document has a line break after every end element tag but no elements are indented. Otherwise, this string must only contain spaces or tabs; the XML document has a line break after every end element and each element start is prepended with a repetition of this string. The string is repeated according to the element's nesting level.
lineLength Input maximum line length. If 0 there is no maximum. Otherwise, a line break is added before an XML attribute is written, if the attribute would have caused the current line to exceed this length.

OSGeo::FDO::Common::Xml::XmlWriter::XmlWriter System::String *  fileName,
System::Boolean  defaultRoot,
OSGeo::FDO::Common::Xml::XmlWriter::LineFormat  lineFormat
 

Constructs an XML writer on a file.

Parameters:
fileName Input name of the file to write.
defaultRoot true: all elements written are wrapped in a default root element, named "DataStore". false: the default root element is not written. In this case, the first element written (via WriteStartElement() ) becomes the root element. The caller is responsible for ensuring that only one root element is written (the XML standard disallows multiple root elements).
lineFormat Input indentation string for XML elements. If NULL the XML document contains no line breaks and elements are not indented. if L"" then the XML document has a line break after every end element tag but no elements are indented. Otherwise, this string must only contain spaces or tabs; the XML document has a line break after every end element and each element start is prepended with a repetition of this string. The string is repeated according to the element's nesting level.

OSGeo::FDO::Common::Xml::XmlWriter::XmlWriter System::String *  fileName,
System::Boolean  defaultRoot
 

Constructs an XML writer on a file.

Parameters:
fileName Input name of the file to write.
defaultRoot true: all elements written are wrapped in a default root element, named "DataStore". false: the default root element is not written. In this case, the first element written (via WriteStartElement() ) becomes the root element. The caller is responsible for ensuring that only one root element is written (the XML standard disallows multiple root elements).

OSGeo::FDO::Common::Xml::XmlWriter::XmlWriter System::String *  fileName  ) 
 

Constructs an XML writer on a file.

Parameters:
fileName Input name of the file to write.

OSGeo::FDO::Common::Xml::XmlWriter::XmlWriter OSGeo::FDO::Common::Io::IoStream stream,
System::Boolean  defaultRoot,
OSGeo::FDO::Common::Xml::XmlWriter::LineFormat  lineFormat,
System::UInt32  lineLength
 

Constructs an XML writer on a stream.

Parameters:
stream Input the stream to write.
defaultRoot true: all elements written are wrapped in a default root element, named "DataStore". false: the default root element is not written. In this case, the first element written (via WriteStartElement() ) becomes the root element. The caller is responsible for ensuring that only one root element is written (the XML standard disallows multiple root elements).
lineFormat Input indentation string for XML elements. If NULL the XML document contains no line breaks and elements are not indented. if L"" then the XML document has a line break after every end element tag but no elements are indented. Otherwise, this string must only contain spaces or tabs; the XML document has a line break after every end element and each element start is prepended with a repetition of this string. The string is repeated according to the element's nesting level.
lineLength Input maximum line length. If 0 there is no maximum. Otherwise, a line break is added before an XML attribute is written, if the attribute would have caused the current line to exceed this length.

OSGeo::FDO::Common::Xml::XmlWriter::XmlWriter OSGeo::FDO::Common::Io::IoStream stream,
System::Boolean  defaultRoot,
OSGeo::FDO::Common::Xml::XmlWriter::LineFormat  lineFormat
 

Constructs an XML writer on a stream.

Parameters:
stream Input the stream to write.
defaultRoot true: all elements written are wrapped in a default root element, named "DataStore". false: the default root element is not written. In this case, the first element written (via WriteStartElement() ) becomes the root element. The caller is responsible for ensuring that only one root element is written (the XML standard disallows multiple root elements).
lineFormat 

OSGeo::FDO::Common::Xml::XmlWriter::XmlWriter OSGeo::FDO::Common::Io::IoStream stream,
System::Boolean  defaultRoot
 

Constructs an XML writer on a stream.

Parameters:
stream Input the stream to write.
defaultRoot true: all elements written are wrapped in a default root element, named "DataStore". false: the default root element is not written. In this case, the first element written (via WriteStartElement() ) becomes the root element. The caller is responsible for ensuring that only one root element is written (the XML standard disallows multiple root elements).

OSGeo::FDO::Common::Xml::XmlWriter::XmlWriter OSGeo::FDO::Common::Io::IoStream stream  ) 
 

Constructs an XML writer on a stream.

Parameters:
stream Input the stream to write.

OSGeo::FDO::Common::Xml::XmlWriter::XmlWriter OSGeo::FDO::Common::Io::IoTextWriter writer,
System::Boolean  defaultRoot,
OSGeo::FDO::Common::Xml::XmlWriter::LineFormat  lineFormat,
System::UInt32  lineLength
 

Constructs an XML writer on a text writer.

Parameters:
writer Input the text writer.
defaultRoot true: all elements written are wrapped in a default root element, named "DataStore". false: the default root element is not written. In this case, the first element written (via WriteStartElement() ) becomes the root element. The caller is responsible for ensuring that only one root element is written (the XML standard disallows multiple root elements).
lineFormat Input indentation string for XML elements. If NULL the XML document contains no line breaks and elements are not indented. if L"" then the XML document has a line break after every end element tag but no elements are indented. Otherwise, this string must only contain spaces or tabs; the XML document has a line break after every end element and each element start is prepended with a repetition of this string. The string is repeated according to the element's nesting level.
lineLength Input maximum line length. If 0 there is no maximum. Otherwise, a line break is added before an XML attribute is written, if the attribute would have caused the current line to exceed this length.

OSGeo::FDO::Common::Xml::XmlWriter::XmlWriter OSGeo::FDO::Common::Io::IoTextWriter writer,
System::Boolean  defaultRoot,
OSGeo::FDO::Common::Xml::XmlWriter::LineFormat  lineFormat
 

Constructs an XML writer on a text writer.

Parameters:
writer Input the text writer.
defaultRoot true: all elements written are wrapped in a default root element, named "DataStore". false: the default root element is not written. In this case, the first element written (via WriteStartElement() ) becomes the root element. The caller is responsible for ensuring that only one root element is written (the XML standard disallows multiple root elements).
lineFormat Input indentation string for XML elements. If NULL the XML document contains no line breaks and elements are not indented. if L"" then the XML document has a line break after every end element tag but no elements are indented. Otherwise, this string must only contain spaces or tabs; the XML document has a line break after every end element and each element start is prepended with a repetition of this string. The string is repeated according to the element's nesting level.

OSGeo::FDO::Common::Xml::XmlWriter::XmlWriter OSGeo::FDO::Common::Io::IoTextWriter writer,
System::Boolean  defaultRoot
 

Constructs an XML writer on a text writer.

Parameters:
writer Input the text writer.
defaultRoot true: all elements written are wrapped in a default root element, named "DataStore". false: the default root element is not written. In this case, the first element written (via WriteStartElement() ) becomes the root element. The caller is responsible for ensuring that only one root element is written (the XML standard disallows multiple root elements).

OSGeo::FDO::Common::Xml::XmlWriter::XmlWriter OSGeo::FDO::Common::Io::IoTextWriter writer  ) 
 

Constructs an XML writer on a text writer.

Parameters:
writer Input the text writer.

Member Function Documentation

System::Void OSGeo::FDO::Common::Xml::XmlWriter::Close  ) 
 

Closes this XML Writer by writing end tags for all elements currently open. Once this function is called, no more elements can be added to the output document.

System::String* OSGeo::FDO::Common::Xml::XmlWriter::EncodeName System::String *  name  ) 
 

utility function that converts FDO element names to valid XML element or attribute names. Conversion is done by changing each invalid character to a hex pattern ( "-xnnnn-" ).

Parameters:
name Input the name to encode (convert).
Returns:
Returns the encoded name.

__property System::Boolean OSGeo::FDO::Common::Xml::XmlWriter::get_DefaultRoot  ) 
 

Gets the current default root state.

Returns:
Returns true if the default root element will be written, false otherwise.

__property OSGeo ::FDO ::Common ::Io ::IoStream* OSGeo::FDO::Common::Xml::XmlWriter::get_Stream  ) 
 

Gets the underlying stream. If a text writer was passed to this object then the stream for this text writer is returned. If a stream was passed to this object then this stream is returned. If a file name as passed then a auto-generated stream (wrapped around the file) is returned.

Returns:
Returns the underlying stream

__property OSGeo ::FDO ::Common ::Io ::IoTextWriter* OSGeo::FDO::Common::Xml::XmlWriter::get_TextWriter  ) 
 

Gets the underlying text writer. If a text writer was passed to this object then this text writeer is returned. Otherwise, an auto-generated text writer is returned (a text writer wrapped around the file name or stream that was passed to this object).

Returns:
Returns the underlying text writer

System::Boolean OSGeo::FDO::Common::Xml::XmlWriter::IsValidName System::String *  name  ) 
 

Checks if a string is a valid XML 1.0 element or attribute name.

Parameters:
name Input the string to check.
Returns:
Returns true if the string is a valid name, false otherwise.

System::Void OSGeo::FDO::Common::Xml::XmlWriter::ReleaseUnmanagedObject  )  [protected, virtual]
 

DOXYGEN-IGNORE

Reimplemented from OSGeo::FDO::Runtime::Disposable.

__property System::Void OSGeo::FDO::Common::Xml::XmlWriter::set_DefaultRoot System::Boolean  defaultRoot  ) 
 

Sets whether to write the default root element. Must be called before the first element is written, otherwise an exception is thrown.

Parameters:
defaultRoot true: use the default root element ("DataStore") as the root element. false: caller is responsible for writing the root element.

System::String* OSGeo::FDO::Common::Xml::XmlWriter::UriToQName System::String *  location,
System::String *  localName
 

System::String* OSGeo::FDO::Common::Xml::XmlWriter::UriToQName System::String *  location,
System::String *  localName,
System::Boolean  isElement
 

Given an element's or attribute's globally unique name ( uri and local name ), this function returns its fully qualified name as per the XML document being written, or the unqualified name if the uri is the default namespace. This is done by searching for the current namespace declaration that references the uri.

Remarks:
If a matching default namespace declaration ( "xmlns=<uri>" ) was found and the name is for an element then the localName is returned.
Note:
According to the XML 1.0 specification, default namespaces do not apply to attribute names, so the default namespace is ignored when the given name is not for an element.
Otherwise, if a matching namespace declaration was found then "[namespace]:[localName]" is returned.
Otherwise, L"" is returned (unable to determine qualified name).
Parameters:
location Input the URI corresponding to an element.
localName Input the local name corresponding to an element.
isElement Input a boolean flag indicating that the URI corresponds to an element.
Returns:
Returns the fully qualified name corresponding to the uri.

System::Void OSGeo::FDO::Common::Xml::XmlWriter::WriteAttribute System::String *  attributeName,
System::String *  attributeValue
 

Writes an attribute to the current element. An Exception is thrown if this function is called immediately after WriteEndElement().

Parameters:
attributeName Input the element name. Must be a valid XML 1.0 attribute name.
attributeValue Input the element value.

System::Void OSGeo::FDO::Common::Xml::XmlWriter::WriteBytes System::Byte  bytes[],
System::UInt32  count
 

Writes arbitrary bytes to the XML Writer. Caller is responsible for ensuring that the text does not introduce any errors into the XML document.

Parameters:
bytes Input characters to write.
count Input the number of bytes to write

System::Void OSGeo::FDO::Common::Xml::XmlWriter::WriteCharacters System::String *  characters  ) 
 

Writes simple (character) content for the current element. This function can be called multiple times for the same element. The characters are appended to the element's content. An Exception is thrown if there is no current element.

Parameters:
characters Input characters to append to the element content.

System::Void OSGeo::FDO::Common::Xml::XmlWriter::WriteEndElement  ) 
 

Writes the end tag for the current element to the document. An Exception is thrown if there is no element to end.

System::Void OSGeo::FDO::Common::Xml::XmlWriter::WriteStartElement System::String *  elementName  ) 
 

Writes an element start tag to the document.

Parameters:
elementName Input the element name. Must be a valid XML 1.0 element name.

Comments or suggestions? Send us feedback.