FDO .NET API Reference Feature Data Objects

mgXmlWriter.h

Go to the documentation of this file.
00001 /*
00002 * Copyright (C) 2004-2006  Autodesk, Inc.
00003 * 
00004 * This library is free software; you can redistribute it and/or
00005 * modify it under the terms of version 2.1 of the GNU Lesser
00006 * General Public License as published by the Free Software Foundation.
00007 * 
00008 * This library is distributed in the hope that it will be useful,
00009 * but WITHOUT ANY WARRANTY; without even the implied warranty of
00010 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00011 * Lesser General Public License for more details.
00012 * 
00013 * You should have received a copy of the GNU Lesser General Public
00014 * License along with this library; if not, write to the Free Software
00015 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
00016 *
00017 */
00018 
00019 #pragma once
00020 
00021 #include "Runtime\Disposable.h"
00022 
00023 class FdoXmlWriter;
00024 
00025 BEGIN_NAMESPACE_OSGEO_COMMON_IO
00026 public __gc class IoStream;
00027 public __gc class IoTextWriter;
00028 END_NAMESPACE_OSGEO_COMMON_IO
00029 
00030 using namespace NAMESPACE_OSGEO_COMMON_IO;
00031 
00032 BEGIN_NAMESPACE_OSGEO_COMMON_XML
00033 
00034 /// \ingroup (OSGeoFDOCommonXml)
00035 /// \brief
00036 /// XmlWriter writes an XML document to a text or binary stream. 
00037 /// Note: The XML document is not completely written until this object
00038 /// is destroyed by releasing all references to it. Therefore, this object
00039 /// must be destroyed before reading back the document being written.
00040 public __gc class XmlWriter : public NAMESPACE_OSGEO_RUNTIME::Disposable
00041 {
00042 public:
00043     /// \brief
00044     /// XmlWriter::LineFormat specifies whether the output XML document
00045     /// has line breaks or indentation.
00046     /// 
00047     /// \param LineFormat_None 
00048     /// The document is written without line breaks or element indentation.
00049     /// \param LineFormat_Break 
00050     /// The document is written with a line break after:
00051     /// <ul>
00052     /// <li> every end element tag
00053     /// <li> every start tag for elements with complex content (sub-elements)
00054     /// </ul>
00055     /// Elements are not indented.
00056     /// \param LineFormat_Indent 
00057     /// Same as LineFormat_Break, except that each element immediately following 
00058     /// a line break is indented by a certain number of spaces. The number of
00059     /// spaces is the element's nesting level within the document X 3. The root
00060     /// element has nesting level 0.
00061     /// 
00062     __value enum LineFormat 
00063     {
00064         LineFormat_None = FdoXmlWriter::LineFormat_None,
00065         LineFormat_Break = FdoXmlWriter::LineFormat_Break,
00066         LineFormat_Indent = FdoXmlWriter::LineFormat_Indent
00067     };
00068 
00069     /// \brief
00070     /// Constructs an XML writer on a file
00071     /// 
00072     /// \param fileName 
00073     /// Input name of the file to write.
00074     /// \param defaultRoot 
00075     /// true: all elements written are wrapped in a default root element, named "DataStore".
00076     /// false: the default root element is not written. In this case, the first 
00077     /// element written (via  WriteStartElement() ) becomes the root element. 
00078     /// The caller is responsible for ensuring that only one root element is written 
00079     /// (the XML standard disallows multiple root elements).
00080     /// \param lineFormat 
00081     /// Input indentation string for XML elements. If NULL
00082     /// the XML document contains no line breaks and elements are not indented. 
00083     /// if L"" then the XML document has a line break after every end element
00084     /// tag but no elements are indented. Otherwise, this string must only 
00085     /// contain spaces or tabs; the XML document has a line break after every end element
00086     /// and each element start is prepended with a repetition of this string.
00087     /// The string is repeated according to the element's nesting level.
00088     /// \param lineLength 
00089     /// Input maximum line length. If 0 there is 
00090     /// no maximum. Otherwise, a line break is added before an XML attribute is
00091     /// written, if the attribute would have caused the current line to exceed
00092     /// this length.
00093     /// 
00094     XmlWriter(System::String* fileName, System::Boolean defaultRoot, NAMESPACE_OSGEO_COMMON_XML::XmlWriter::LineFormat lineFormat, System::UInt32 lineLength);
00095 
00096     /// \brief
00097     /// Constructs an XML writer on a file
00098     /// 
00099     /// \param fileName 
00100     /// Input name of the file to write.
00101     /// \param defaultRoot 
00102     /// true: all elements written are wrapped in a default root element, named "DataStore".
00103     /// false: the default root element is not written. In this case, the first 
00104     /// element written (via  WriteStartElement() ) becomes the root element. 
00105     /// The caller is responsible for ensuring that only one root element is written 
00106     /// (the XML standard disallows multiple root elements).
00107     /// \param lineFormat 
00108     /// Input indentation string for XML elements. If NULL
00109     /// the XML document contains no line breaks and elements are not indented. 
00110     /// if L"" then the XML document has a line break after every end element
00111     /// tag but no elements are indented. Otherwise, this string must only 
00112     /// contain spaces or tabs; the XML document has a line break after every end element
00113     /// and each element start is prepended with a repetition of this string.
00114     /// The string is repeated according to the element's nesting level.
00115     /// 
00116     XmlWriter(System::String* fileName, System::Boolean defaultRoot, NAMESPACE_OSGEO_COMMON_XML::XmlWriter::LineFormat lineFormat);
00117 
00118     /// \brief
00119     /// Constructs an XML writer on a file
00120     /// 
00121     /// \param fileName 
00122     /// Input name of the file to write.
00123     /// \param defaultRoot 
00124     /// true: all elements written are wrapped in a default root element, named "DataStore".
00125     /// false: the default root element is not written. In this case, the first 
00126     /// element written (via  WriteStartElement() ) becomes the root element. 
00127     /// The caller is responsible for ensuring that only one root element is written 
00128     /// (the XML standard disallows multiple root elements).
00129     /// 
00130     XmlWriter(System::String* fileName, System::Boolean defaultRoot);
00131 
00132     /// \brief
00133     /// Constructs an XML writer on a file
00134     /// 
00135     /// \param fileName 
00136     /// Input name of the file to write.
00137     /// 
00138     XmlWriter(System::String* fileName);
00139 
00140     /// \brief
00141     /// Constructs an XML writer on a stream
00142     /// 
00143     /// \param stream 
00144     /// Input the stream to write.
00145     /// \param defaultRoot 
00146     /// true: all elements written are wrapped in a default root element, named "DataStore".
00147     /// false: the default root element is not written. In this case, the first 
00148     /// element written (via  WriteStartElement() ) becomes the root element. 
00149     /// The caller is responsible for ensuring that only one root element is written 
00150     /// (the XML standard disallows multiple root elements).
00151     /// \param lineFormat 
00152     /// Input indentation string for XML elements. If NULL
00153     /// the XML document contains no line breaks and elements are not indented. 
00154     /// if L"" then the XML document has a line break after every end element
00155     /// tag but no elements are indented. Otherwise, this string must only 
00156     /// contain spaces or tabs; the XML document has a line break after every end element
00157     /// and each element start is prepended with a repetition of this string.
00158     /// The string is repeated according to the element's nesting level.
00159     /// \param lineLength 
00160     /// Input maximum line length. If 0 there is 
00161     /// no maximum. Otherwise, a line break is added before an XML attribute is
00162     /// written, if the attribute would have caused the current line to exceed
00163     /// this length.
00164     /// 
00165     XmlWriter(NAMESPACE_OSGEO_COMMON_IO::IoStream* stream, System::Boolean defaultRoot, NAMESPACE_OSGEO_COMMON_XML::XmlWriter::LineFormat lineFormat, System::UInt32 lineLength);
00166 
00167     /// \brief
00168     /// Constructs an XML writer on a stream
00169     /// 
00170     /// \param stream 
00171     /// Input the stream to write.
00172     /// \param defaultRoot 
00173     /// true: all elements written are wrapped in a default root element, named "DataStore".
00174     /// false: the default root element is not written. In this case, the first 
00175     /// element written (via  WriteStartElement() ) becomes the root element. 
00176     /// The caller is responsible for ensuring that only one root element is written 
00177     /// (the XML standard disallows multiple root elements).
00178     /// \param lineFormat 
00179     /// 
00180     XmlWriter(NAMESPACE_OSGEO_COMMON_IO::IoStream* stream, System::Boolean defaultRoot, NAMESPACE_OSGEO_COMMON_XML::XmlWriter::LineFormat lineFormat);
00181 
00182     /// \brief
00183     /// Constructs an XML writer on a stream
00184     /// 
00185     /// \param stream 
00186     /// Input the stream to write.
00187     /// \param defaultRoot 
00188     /// true: all elements written are wrapped in a default root element, named "DataStore".
00189     /// false: the default root element is not written. In this case, the first 
00190     /// element written (via  WriteStartElement() ) becomes the root element. 
00191     /// The caller is responsible for ensuring that only one root element is written 
00192     /// (the XML standard disallows multiple root elements).
00193     /// 
00194     XmlWriter(NAMESPACE_OSGEO_COMMON_IO::IoStream* stream, System::Boolean defaultRoot);
00195 
00196     /// \brief
00197     /// Constructs an XML writer on a stream
00198     /// 
00199     /// \param stream 
00200     /// Input the stream to write.
00201     /// 
00202     XmlWriter(NAMESPACE_OSGEO_COMMON_IO::IoStream* stream);
00203 
00204     /// \brief
00205     /// Constructs an XML writer on a text writer
00206     /// 
00207     /// \param writer 
00208     /// Input the text writer.
00209     /// \param defaultRoot 
00210     /// true: all elements written are wrapped in a default root element, named "DataStore".
00211     /// false: the default root element is not written. In this case, the first 
00212     /// element written (via  WriteStartElement() ) becomes the root element. 
00213     /// The caller is responsible for ensuring that only one root element is written 
00214     /// (the XML standard disallows multiple root elements).
00215     /// \param lineFormat 
00216     /// Input indentation string for XML elements. If NULL
00217     /// the XML document contains no line breaks and elements are not indented. 
00218     /// if L"" then the XML document has a line break after every end element
00219     /// tag but no elements are indented. Otherwise, this string must only 
00220     /// contain spaces or tabs; the XML document has a line break after every end element
00221     /// and each element start is prepended with a repetition of this string.
00222     /// The string is repeated according to the element's nesting level.
00223     /// \param lineLength 
00224     /// Input maximum line length. If 0 there is 
00225     /// no maximum. Otherwise, a line break is added before an XML attribute is
00226     /// written, if the attribute would have caused the current line to exceed
00227     /// this length.
00228     /// 
00229     XmlWriter(NAMESPACE_OSGEO_COMMON_IO::IoTextWriter* writer, System::Boolean defaultRoot, NAMESPACE_OSGEO_COMMON_XML::XmlWriter::LineFormat lineFormat, System::UInt32 lineLength);
00230 
00231     /// \brief
00232     /// Constructs an XML writer on a text writer
00233     /// 
00234     /// \param writer 
00235     /// Input the text writer.
00236     /// \param defaultRoot 
00237     /// true: all elements written are wrapped in a default root element, named "DataStore".
00238     /// false: the default root element is not written. In this case, the first 
00239     /// element written (via  WriteStartElement() ) becomes the root element. 
00240     /// The caller is responsible for ensuring that only one root element is written 
00241     /// (the XML standard disallows multiple root elements).
00242     /// \param lineFormat 
00243     /// Input indentation string for XML elements. If NULL
00244     /// the XML document contains no line breaks and elements are not indented. 
00245     /// if L"" then the XML document has a line break after every end element
00246     /// tag but no elements are indented. Otherwise, this string must only 
00247     /// contain spaces or tabs; the XML document has a line break after every end element
00248     /// and each element start is prepended with a repetition of this string.
00249     /// The string is repeated according to the element's nesting level.
00250     /// 
00251     XmlWriter(NAMESPACE_OSGEO_COMMON_IO::IoTextWriter* writer, System::Boolean defaultRoot, NAMESPACE_OSGEO_COMMON_XML::XmlWriter::LineFormat lineFormat);
00252 
00253     /// \brief
00254     /// Constructs an XML writer on a text writer
00255     /// 
00256     /// \param writer 
00257     /// Input the text writer.
00258     /// \param defaultRoot 
00259     /// true: all elements written are wrapped in a default root element, named "DataStore".
00260     /// false: the default root element is not written. In this case, the first 
00261     /// element written (via  WriteStartElement() ) becomes the root element. 
00262     /// The caller is responsible for ensuring that only one root element is written 
00263     /// (the XML standard disallows multiple root elements).
00264     /// 
00265     XmlWriter(NAMESPACE_OSGEO_COMMON_IO::IoTextWriter* writer, System::Boolean defaultRoot);
00266 
00267     /// \brief
00268     /// Constructs an XML writer on a text writer
00269     /// 
00270     /// \param writer 
00271     /// Input the text writer.
00272     /// 
00273     XmlWriter(NAMESPACE_OSGEO_COMMON_IO::IoTextWriter* writer);
00274 
00275     /// \brief
00276     /// Gets the underlying text writer. If a text writer was passed to this object
00277     /// then this text writeer is returned.
00278     /// Otherwise, an auto-generated text writer is returned (a text writer
00279     /// wrapped around the file name or stream that was passed to this object)
00280     /// 
00281     /// \return
00282     /// Returns the underlying text writer
00283     /// 
00284     __property NAMESPACE_OSGEO_COMMON_IO::IoTextWriter* get_TextWriter();
00285 
00286     /// \brief
00287     /// Gets the underlying stream. If a text writer was passed to this object
00288     /// then the stream for this text writer is returned.
00289     /// If a stream was passed to this object then this stream is returned.
00290     /// If a file name as passed then a auto-generated stream (wrapped around
00291     /// the file) is returned.
00292     /// 
00293     /// \return
00294     /// Returns the underlying stream
00295     /// 
00296     __property NAMESPACE_OSGEO_COMMON_IO::IoStream* get_Stream();
00297 
00298     /// \brief
00299     /// Gets the current default root state.
00300     /// 
00301     /// \return
00302     /// Returns true if the default root element will be written, false otherwise.
00303     /// 
00304     __property System::Boolean get_DefaultRoot();
00305 
00306     /// \brief
00307     /// Sets whether to write the default root element.
00308     /// Must be called before the first element is written,
00309     /// otherwise an exception is thrown
00310     /// 
00311     /// \param defaultRoot 
00312     /// true: use the default root element ("DataStore") as the root element.
00313     /// false: caller is responsible for writing the root element.
00314     /// 
00315     __property System::Void  set_DefaultRoot(System::Boolean defaultRoot );
00316 
00317     /// \brief
00318     /// Closes this XML Writer by writing end tags for all
00319     /// elements currently open. Once this function is called, no more
00320     /// elements can be added to the output document.
00321     /// 
00322     System::Void Close();
00323 
00324     /// \brief
00325     /// Writes an element start tag to the document
00326     /// 
00327     /// \param elementName 
00328     /// Input the element name. Must be a valid
00329     /// XML 1.0 element name.
00330     /// 
00331     System::Void WriteStartElement(System::String* elementName );
00332 
00333     /// \brief
00334     /// Writes the end tag for the current element to the document.
00335     /// An Exception is thrown if there is no element to end.
00336     /// 
00337     System::Void WriteEndElement();
00338 
00339     /// \brief
00340     /// Writes an attribute to the current element.
00341     /// An Exception is thrown if this function is called immediately after
00342     /// WriteEndElement().
00343     /// 
00344     /// \param attributeName 
00345     /// Input the element name. Must be a valid
00346     /// XML 1.0 attribute name.
00347     /// \param attributeValue 
00348     /// Input the element value.
00349     /// 
00350     System::Void WriteAttribute( System::String* attributeName, System::String* attributeValue );
00351 
00352     /// \brief
00353     /// Writes simple (character) content for the current element. This function
00354     /// can be called multiple times for the same element. The characters are appended
00355     /// to the element's content. An Exception is thrown if there is no current 
00356     /// element.
00357     /// 
00358     /// \param characters 
00359     /// Input characters to append to the element content.
00360     /// 
00361     System::Void WriteCharacters( System::String* characters );
00362 
00363     /// \brief
00364     /// Writes arbitrary bytes to the XML Writer. Caller is responsible
00365     /// for ensuring that the text does not introduce any errors into the 
00366     /// XML document.
00367     /// 
00368     /// \param bytes 
00369     /// Input characters to write.
00370     /// 
00371     /// \param count 
00372     /// Input the number of bytes to write
00373     /// 
00374     System::Void WriteBytes( System::Byte bytes [],  System::UInt32 count );
00375 
00376     /// \brief
00377     /// utility function that converts FDO element names to valid XML
00378     /// element or attribute names. Conversion is done by changing each invalid 
00379     /// character to a hex pattern ( "-xnnnn-" ).
00380     /// 
00381     /// \param name 
00382     /// Input the name to encode (convert).
00383     /// 
00384     /// \return
00385     /// Returns the encoded name.
00386     /// 
00387     System::String* EncodeName(System::String* name);
00388 
00389     /// \brief
00390     /// Checks if a string is a valid XML 1.0 element or attribute name.
00391     /// 
00392     /// \param name 
00393     /// Input the string to check.
00394     /// 
00395     /// \return
00396     /// Returns true if the string is a valid name, false otherwise.
00397     /// 
00398     System::Boolean IsValidName(System::String* name);
00399 
00400     /// \brief
00401     /// Given an element's or attribute's globally unique name ( uri and local name ),
00402     /// this function returns its fully qualified name as per the
00403     /// XML document being written, or the unqualified name if the uri is 
00404     /// the default namespace. This is done by searching for the current 
00405     /// namespace declaration that references the uri. 
00406     /// 
00407     /// \remarks
00408     /// If a matching default namespace declaration ( "xmlns=<uri>" ) was
00409     /// found and the name is for an element then the localName is returned.
00410     /// \note
00411     /// According to the XML 1.0 specification, default namespaces do 
00412     /// not apply to attribute names, so the default namespace is ignored when the 
00413     /// given name is not for an element.
00414     /// \n
00415     /// Otherwise, if a matching namespace declaration was found then 
00416     /// "[namespace]:[localName]" is returned.
00417     /// \n
00418     /// Otherwise, L"" is returned (unable to determine qualified name).
00419     /// 
00420     /// \param location 
00421     /// Input the URI corresponding to an element.
00422     /// \param localName 
00423     /// Input the local name corresponding to an element.
00424     /// \param isElement 
00425     /// Input a boolean flag indicating that the URI corresponds to an element.
00426     /// 
00427     /// \return
00428     /// Returns the fully qualified name corresponding to the uri.
00429     /// 
00430     System::String* UriToQName( System::String* location, System::String* localName, System::Boolean isElement);
00431     System::String* UriToQName( System::String* location, System::String* localName);
00432 
00433 /// \cond DOXYGEN-IGNORE
00434 protected:
00435     System::Void ReleaseUnmanagedObject();
00436 
00437 public private:
00438     XmlWriter(System::IntPtr unmanaged, System::Boolean autoDelete);
00439 
00440     inline FdoXmlWriter* GetImpObj();
00441 /// \endcond
00442 };
00443 END_NAMESPACE_OSGEO_COMMON_XML
00444 
00445 

Comments or suggestions? Send us feedback.