Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/serialization/doc/exceptions.html @ 20

Last change on this file since 20 was 12, checked in by landauf, 18 years ago

added boost
File size: 11.9 KB
Line 
1<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<!--
4(C) Copyright 2002-4 Robert Ramey - http://www.rrsd.com .
5Use, modification and distribution is subject to the Boost Software
6License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
7http://www.boost.org/LICENSE_1_0.txt)
8-->
9<head>
10<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
11<link rel="stylesheet" type="text/css" href="../../../boost.css">
12<link rel="stylesheet" type="text/css" href="style.css">
13<title>Serialization - Archive Exceptions</title>
14</head>
15<body link="#0000ff" vlink="#800080">
16<table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
17  <tr> 
18    <td valign="top" width="300"> 
19      <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
20    </td>
21    <td valign="top"> 
22      <h1 align="center">Serialization</h1>
23      <h2 align="center">Archive Exceptions</h2>
24    </td>
25  </tr>
26</table>
27<hr>
28<dl class="page-index">
29  <dt><a href="#unregistered_class"><code style="white-space: normal">unregistered_class</code></a>
30  <dt><a href="#invalid_signature"><code style="white-space: normal">invalid_signature</code></a>
31  <dt><a href="#unsupported_version"><code style="white-space: normal">unsupported_version</code></a>
32  <dt><a href="#pointer_conflict"><code style="white-space: normal">pointer_conflict</code></a>
33  <dt><a href="#incompatible_native_format"><code style="white-space: normal">incompatible_native_format</code></a>
34  <dt><a href="#array_size_too_short"><code style="white-space: normal">array_size_too_short</code></a>
35  <dt><a href="#stream_error"><code style="white-space: normal">stream_error</code></a>
36  <dt><a href="#invalid_class_name"><code style="white-space: normal">invalid_class_name</code></a>
37  <dt><a href="#unregistered_class"><code style="white-space: normal">unregistered_class</code></a>
38  <dt><a href="#xml_archive_parsing_error"><code style="white-space: normal">xml_archive_parsing_error</code></a>
39  <dt><a href="#xml_archive_tag_mismatch"><code style="white-space: normal">xml_archive_tag_mismatch</code></a>
40  <dt><a href="#xml_archive_tag_name_error"><code style="white-space: normal">xml_archive_tag_name_error</code></a>
41</dl>
42
43Archive operators can throw a <code style="white-space: normal">boost::archive_exception</code>
44object which can be caught by an application program.  These exceptions are defined
45in the files <a target="archive_exception_hpp" href="../../../boost/archive/archive_exception.hpp">
46boost/archive/archive_exception.hpp</a> and <a target="archive_xml_exception_hpp" href="../../../boost/archive/archive_exception.hpp">
47boost/archive/archive_xml_exception.hpp</a>.
48<pre><code>
49namespace boost {
50namespace archive {
51
52class archive_exception  : public std::exception
53{
54public:
55    typedef enum {
56        unregistered_class,     // attempt to serialize a pointer of an
57                                // an unregistered class
58        invalid_signature,      // first line of archive does not contain
59                                // expected string
60        unsupported_version,    // archive created with library version subsequent
61                                // to this one
62        pointer_conflict        // an attempt has been made to directly serialize
63                                // an object after having already serialized the same
64                                // object through a pointer.  Were this permitted,
65                                // it the archive load would result in the creation
66                                // of extraneous object.
67        incompatible_native_format, // attempt to read native binary format
68                                // on incompatible platform
69        array_size_too_short,   // array being loaded doesn't fit in array allocated
70        stream_error            // i/o error on stream
71        invalid_class_name,     // class name greater than the maximum permitted.
72                                // most likely a corrupted archive or an attempt
73                                // to insert virus via buffer overrun method.
74        unregistered_cast       // base - derived relationship not registered with
75                                // void_cast_register
76    } exception_code;
77    exception_code code;
78    archive_exception(exception_code c) : code(c) {}
79    virtual const char *what( ) const throw();
80};
81
82class xml_archive_exception : public virtual archive_exception
83{
84public:
85    typedef enum {
86        xml_archive_parsing_error,  // archive doesn't contain expected data
87        xml_archive_tag_mismatch,   // start/end tag in archive doesn't match program
88        xml_archive_tag_name_error  // tag name contains invalid characters
89
90    } exception_code;
91    xml_archive_exception(exception_code c){}
92    virtual const char *what( ) const throw();
93};
94
95} // archive
96} // boost
97</code></pre>
98<p>
99<h3><a name="unregistered_class"><code style="white-space: normal">unregistered_class</code></a></h3>
100An attempt has been made to serialize a polymorphic class through a pointer
101without either registering it or associating it with an export key.  This can also occur
102when using a new archive how class name has not been added to the system with the
103<code style="white-space: normal">BOOST_ARCHIVE_CUSTOM_ARCHIVE_TYPES</code> macro.
104
105<h3><a name="invalid_signature"><code style="white-space: normal">invalid_signature</code></a></h3>
106Archives are initiated with a known string.  If this string is not found when
107the archive is opened, It is presumed that this file is not a valid archive and this
108exception is thrown.
109
110<h3><a name="unsupported_version"><code style="white-space: normal">unsupported_version</code></a></h3>
111This system assigns a version number of 2 to all archives created.  Note that this is in
112no way related to version number of classes used by application programs. This refers
113to the version of the serialization system used to create the archive. Future versions
114of this serialization system will be able to identify archives created under previous
115(i.e. this) system and alter the loading procedure accordingly.  Hence, future enhancements
116to this serialization system should not obsolete any existing archive files.  It is only
117necessary to increment this version number when the newer system creates archives
118incompatible in format with the current one.
119<p>Should it ever occur that an older program attempts to read newer archives whose
120format has changed, this exception is thrown.
121
122<h3><a name="pointer_conflict"><code style="white-space: normal">pointer_conflict</code></a></h3>
123To understand what this exception means consider the following scenario
124<pre><code>
125template&lt;class Archive&gt;
126void T::save(Archive &ar) const
127{
128    const A * aptr = &a;
129    ar << aptr;          // save an instance of object of class A through a pointer
130    ...
131    ar << a;             // save an instance of an object of class A
132    assert(aptr == &a);  // this must be true
133}
134
135template&lt;class Archive&gt;
136void T::load(Archive &ar)
137{
138    A * aptr;
139    ar >> aptr;          // create and initialize a new instance of class A
140    ...
141    ar >> a;             // restore state of on object of class A
142    assert(aptr == &a);  // this won't be true
143}
144</pre></code>
145An object is saved first through a pointer then directly.  Upon loading back
146in the same sequence, we first create an new object and load in its data.  Then
147we load the data into another existing object.  Where we started with one
148object during save, we have two objects after restore.  In a more realistic
149situation, it could be very difficult to find this error.  Fortunately,
150these situations can be detected when the archive is created. When
151this occurs, this exception is thrown.
152
153<h3><a name = "incompatible_native_format"><code style="white-space: normal">incompatible_native_format</code></a></h3>
154The library currently supports char text, wide char text and native binary
155archive files. At the beginning of every archive, a signature is written indicating
156the type of archive.  This exception is thrown when an attempt is made to read
157an archive written in a different format.
158
159<h3><a name="array_size_too_short"><code style="white-space: normal">array_size_too_short</code></a></h3>
160An attempt has been made to read an array that is larger than the array size.
161This should only occur when the size of an array in code is reduced after an
162archive has already been created.
163
164<h3><a name="stream_error"><code style="white-space: normal">stream_error</code></a></h3>
165An error has occured durring stream input or ouput.  This includes
166an attempt to read past the end of the file. Text files need a terminating
167new line character at the end of the file which is appended when the
168archive destructor is invoked.  Be sure that an output archive on a stream
169is destroyed before opening an input archive on that same stream.  That is,
170rather than using something like:
171<pre><code>
172std::stringstream ss;
173std::vector&lt;V&gt; v;
174boost::archive::text_oarchive oa(ss);
175oa &lt;&lt; v;
176boost::archive::text_iarchive ia(ss);
177ia &gt;&gt; v;
178</code></pre>
179use
180<pre><code>
181std::stringstream ss;
182std::vector&lt;V&gt; v;
183{
184    boost::archive::text_oarchive oa(ss);
185    oa &lt;&lt; v;
186}
187{
188    boost::archive::text_iarchive ia(ss);
189    ia &gt;&gt; v;
190}
191</code></pre>
192
193<h3><a name="invalid_class_name"><code style="white-space: normal">invalid_class_name</code></a></h3>
194Class name length greater than the maximum permitted. Most likely cause is a corrupted
195archive  or an attempt to insert virus via buffer overrun method.
196
197<h3><a name="unregistered_cast"><code style="white-space: normal">unregistered_cast</code></a></h3>
198In order to support casting between pointers of base and derived classes
199at runtime, a collection of legitimate conversions is maintained by the system.
200Normally this collection is maintained without any explicit action
201on the part of the user of the library.  However, there are special cases
202where this might have to be done explicitly and could be overlooked. This
203is described in <a href="serialization.html#runtimecasting">Runtime Casting</a>.
204This exception is thrown if an attempt is made to convert between two pointers
205whose relationship has not been registered,
206
207<h3><a name="xml_archive_parsing_error"><code style="white-space: normal">xml_archive_parsing_error</code></a></h3>
208The XML generated by the serialization process is intimately coupled to the
209C++ class structure, relationships between objects and the serialization
210specifications.  If these become out of sync in any way, the XML may not map
211to the loading serialization and this exception might be thrown.  This might
212occur for one of the following reasons:
213<ul>
214    <li>The archive has been edited outside the serialization system.  This might
215be possible if only the data is changed and not the XML attributes and nesting
216structure is left unaltered.  But any other editing is likely to render the
217archive unreadable by the serialization library.
218    <li>The serialization has been altered and an archive generated by the old
219code is being read.  That is, versioning has not been properly employed to
220properly deserialize previously created archives.
221</ul>
222
223<h3><a name="xml_archive_tag_mismatch"><code style="white-space: normal">xml_archive_tag_mismatch</code></a></h3>
224This exception will be thrown if the start or end tag of and XML element doesn't match
225the name specified for the object in the program.
226
227<h3><a name="xml_archive_tag_name_error"><code style="white-space: normal">xml_archive_tag_name_error</code></a></h3>
228This exception will be thrown if the tag name contains invalid characters.  Valid characters
229for an XML tag are: upper and lower case letters, digits, and the following punctuation: .(period),
230_(underscore), :(colon), and -(hyphen).
231
232<hr>
233<p><i>&copy; Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004.
234Distributed under the Boost Software License, Version 1.0. (See
235accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
236</i></p>
237</body>
238</html>
Note: See TracBrowser for help on using the repository browser.