FDO API Reference Feature Data Objects
Main Page | Modules | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members

FdoXmlWriter Class Reference

#include <Writer.h>

Inherits FdoDisposable.

Inheritance diagram for FdoXmlWriter:

[legend]
List of all members.

Detailed Description

FdoXmlWriter 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.

Definition at line 31 of file Writer.h.


Public Types

enum  LineFormat {
  LineFormat_None,
  LineFormat_Break,
  LineFormat_Indent
}
 Specifies whether the output XML document has line breaks or indentation. More...

Public Member Functions

FDO_API_COMMON 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.
virtual FDO_API_COMMON FdoStringP EncodeName (FdoStringP name)=0
 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-" ).
FDO_API_COMMON FdoBoolean GetDefaultRoot ()
 Gets the current default root state.
FDO_API_COMMON FdoIoStreamGetStream ()
 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.
FDO_API_COMMON FdoIoTextWriterGetTextWriter ()
 Gets the underlying text writer. If a text writer was passed to this object then this text writer 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).
virtual FDO_API_COMMON FdoBoolean IsValidName (FdoStringP name)=0
 Checks if a string is a valid XML 1.0 element or attribute name.
FDO_API_COMMON void SetDefaultRoot (FdoBoolean defaultRoot)
 Sets whether to write the default root element. Must be called before the first element is written, otherwise an exception is thrown.
FDO_API_COMMON FdoStringP UriToQName (FdoString *uri, FdoString *localName, FdoBoolean isElement=true)
 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.
FDO_API_COMMON void WriteAttribute (FdoString *attributeName, FdoString *attributeValue)
 Writes an attribute to the current element. A FdoXmlException is thrown if this function is called immediately after WriteEndElement().
FDO_API_COMMON void WriteBytes (FdoByte *bytes, FdoSize 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.
FDO_API_COMMON void WriteCharacters (FdoString *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. A FdoXmlException is thrown if there is no current element.
FDO_API_COMMON void WriteEndElement ()
 Writes the end tag for the current element to the document. A FdoXmlException is thrown if there is no element to end.
FDO_API_COMMON void WriteStartElement (FdoString *elementName)
 Writes an element start tag to the document.

Static Public Member Functions

FDO_API_COMMON FdoXmlWriterCreate (FdoIoTextWriter *writer, FdoBoolean defaultRoot=true, LineFormat lineFormat=LineFormat_None, FdoSize lineLength=0)
 Constructs an XML writer on a text writer.
FDO_API_COMMON FdoXmlWriterCreate (FdoIoStream *stream, FdoBoolean defaultRoot=true, LineFormat lineFormat=LineFormat_None, FdoSize lineLength=0)
 Constructs an XML writer on a stream.
FDO_API_COMMON FdoXmlWriterCreate (FdoString *fileName, FdoBoolean defaultRoot=true, LineFormat lineFormat=LineFormat_None, FdoSize lineLength=0)
 Constructs an XML writer on a file.

Protected Member Functions

 FdoXmlWriter (FdoIoTextWriter *writer, FdoBoolean defaultRoot, LineFormat lineFormat, FdoSize lineLength)
 FdoXmlWriter ()
 DOXYGEN-IGNORE
void WritePrologue ()
 Write the prologue when needed.
virtual ~FdoXmlWriter (void)

Member Enumeration Documentation

enum FdoXmlWriter::LineFormat
 

Specifies whether the output XML document has line breaks or indentation.

Enumeration values:
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.

Definition at line 38 of file Writer.h.


Constructor & Destructor Documentation

FdoXmlWriter::FdoXmlWriter  )  [inline, protected]
 

DOXYGEN-IGNORE

Definition at line 310 of file Writer.h.

FdoXmlWriter::FdoXmlWriter FdoIoTextWriter writer,
FdoBoolean  defaultRoot,
LineFormat  lineFormat,
FdoSize  lineLength
[protected]
 

virtual FdoXmlWriter::~FdoXmlWriter void   )  [protected, virtual]
 


Member Function Documentation

FDO_API_COMMON void FdoXmlWriter::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.

FDO_API_COMMON FdoXmlWriter* FdoXmlWriter::Create FdoIoTextWriter writer,
FdoBoolean  defaultRoot = true,
LineFormat  lineFormat = LineFormat_None,
FdoSize  lineLength = 0
[static]
 

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 Line break and indentation options for the output document.
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.
Returns:
Returns FdoXmlWriter

FDO_API_COMMON FdoXmlWriter* FdoXmlWriter::Create FdoIoStream stream,
FdoBoolean  defaultRoot = true,
LineFormat  lineFormat = LineFormat_None,
FdoSize  lineLength = 0
[static]
 

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 Line break and indentation options for the output document.
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.
Returns:
Returns FdoXmlWriter

FDO_API_COMMON FdoXmlWriter* FdoXmlWriter::Create FdoString fileName,
FdoBoolean  defaultRoot = true,
LineFormat  lineFormat = LineFormat_None,
FdoSize  lineLength = 0
[static]
 

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 Line break and indentation options for the output document.
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.
Returns:
Returns FdoXmlWriter

virtual FDO_API_COMMON FdoStringP FdoXmlWriter::EncodeName FdoStringP  name  )  [pure virtual]
 

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.

FDO_API_COMMON FdoBoolean FdoXmlWriter::GetDefaultRoot  )  [inline]
 

Gets the current default root state.

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

Definition at line 177 of file Writer.h.

References FDO_API_COMMON, and FdoBoolean.

FDO_API_COMMON FdoIoStream* FdoXmlWriter::GetStream  )  [inline]
 

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

Definition at line 166 of file Writer.h.

References FDO_API_COMMON.

FDO_API_COMMON FdoIoTextWriter* FdoXmlWriter::GetTextWriter  ) 
 

Gets the underlying text writer. If a text writer was passed to this object then this text writer 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

virtual FDO_API_COMMON FdoBoolean FdoXmlWriter::IsValidName FdoStringP  name  )  [pure virtual]
 

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.

FDO_API_COMMON void FdoXmlWriter::SetDefaultRoot FdoBoolean  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.

FDO_API_COMMON FdoStringP FdoXmlWriter::UriToQName FdoString uri,
FdoString localName,
FdoBoolean  isElement = true
 

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:
uri 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.

FDO_API_COMMON void FdoXmlWriter::WriteAttribute FdoString attributeName,
FdoString attributeValue
 

Writes an attribute to the current element. A FdoXmlException 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.

FDO_API_COMMON void FdoXmlWriter::WriteBytes FdoByte bytes,
FdoSize  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 bytes to write.
count Input count of bytes to write.

FDO_API_COMMON void FdoXmlWriter::WriteCharacters FdoString 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. A FdoXmlException is thrown if there is no current element.

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

FDO_API_COMMON void FdoXmlWriter::WriteEndElement  ) 
 

Writes the end tag for the current element to the document. A FdoXmlException is thrown if there is no element to end.

void FdoXmlWriter::WritePrologue  )  [protected]
 

Write the prologue when needed.

FDO_API_COMMON void FdoXmlWriter::WriteStartElement FdoString elementName  ) 
 

Writes an element start tag to the document.

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

The documentation for this class was generated from the following file:
Comments or suggestions? Send us feedback.