FDO .NET API Reference | Feature Data Objects |
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. |