| 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 . |
|---|
| 5 | Use, modification and distribution is subject to the Boost Software |
|---|
| 6 | License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at |
|---|
| 7 | http://www.boost.org/LICENSE_1_0.txt) |
|---|
| 8 | --> |
|---|
| 9 | <head> |
|---|
| 10 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
|---|
| 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 | |
|---|
| 43 | Archive operators can throw a <code style="white-space: normal">boost::archive_exception</code> |
|---|
| 44 | object which can be caught by an application program. These exceptions are defined |
|---|
| 45 | in the files <a target="archive_exception_hpp" href="../../../boost/archive/archive_exception.hpp"> |
|---|
| 46 | boost/archive/archive_exception.hpp</a> and <a target="archive_xml_exception_hpp" href="../../../boost/archive/archive_exception.hpp"> |
|---|
| 47 | boost/archive/archive_xml_exception.hpp</a>. |
|---|
| 48 | <pre><code> |
|---|
| 49 | namespace boost { |
|---|
| 50 | namespace archive { |
|---|
| 51 | |
|---|
| 52 | class archive_exception : public std::exception |
|---|
| 53 | { |
|---|
| 54 | public: |
|---|
| 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 | |
|---|
| 82 | class xml_archive_exception : public virtual archive_exception |
|---|
| 83 | { |
|---|
| 84 | public: |
|---|
| 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> |
|---|
| 100 | An attempt has been made to serialize a polymorphic class through a pointer |
|---|
| 101 | without either registering it or associating it with an export key. This can also occur |
|---|
| 102 | when 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> |
|---|
| 106 | Archives are initiated with a known string. If this string is not found when |
|---|
| 107 | the archive is opened, It is presumed that this file is not a valid archive and this |
|---|
| 108 | exception is thrown. |
|---|
| 109 | |
|---|
| 110 | <h3><a name="unsupported_version"><code style="white-space: normal">unsupported_version</code></a></h3> |
|---|
| 111 | This system assigns a version number of 2 to all archives created. Note that this is in |
|---|
| 112 | no way related to version number of classes used by application programs. This refers |
|---|
| 113 | to the version of the serialization system used to create the archive. Future versions |
|---|
| 114 | of 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 |
|---|
| 116 | to this serialization system should not obsolete any existing archive files. It is only |
|---|
| 117 | necessary to increment this version number when the newer system creates archives |
|---|
| 118 | incompatible in format with the current one. |
|---|
| 119 | <p>Should it ever occur that an older program attempts to read newer archives whose |
|---|
| 120 | format has changed, this exception is thrown. |
|---|
| 121 | |
|---|
| 122 | <h3><a name="pointer_conflict"><code style="white-space: normal">pointer_conflict</code></a></h3> |
|---|
| 123 | To understand what this exception means consider the following scenario |
|---|
| 124 | <pre><code> |
|---|
| 125 | template<class Archive> |
|---|
| 126 | void 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 | |
|---|
| 135 | template<class Archive> |
|---|
| 136 | void 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> |
|---|
| 145 | An object is saved first through a pointer then directly. Upon loading back |
|---|
| 146 | in the same sequence, we first create an new object and load in its data. Then |
|---|
| 147 | we load the data into another existing object. Where we started with one |
|---|
| 148 | object during save, we have two objects after restore. In a more realistic |
|---|
| 149 | situation, it could be very difficult to find this error. Fortunately, |
|---|
| 150 | these situations can be detected when the archive is created. When |
|---|
| 151 | this occurs, this exception is thrown. |
|---|
| 152 | |
|---|
| 153 | <h3><a name = "incompatible_native_format"><code style="white-space: normal">incompatible_native_format</code></a></h3> |
|---|
| 154 | The library currently supports char text, wide char text and native binary |
|---|
| 155 | archive files. At the beginning of every archive, a signature is written indicating |
|---|
| 156 | the type of archive. This exception is thrown when an attempt is made to read |
|---|
| 157 | an 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> |
|---|
| 160 | An attempt has been made to read an array that is larger than the array size. |
|---|
| 161 | This should only occur when the size of an array in code is reduced after an |
|---|
| 162 | archive has already been created. |
|---|
| 163 | |
|---|
| 164 | <h3><a name="stream_error"><code style="white-space: normal">stream_error</code></a></h3> |
|---|
| 165 | An error has occured during stream input or ouput. Aside from the common |
|---|
| 166 | situations such as a corrupted or truncated input file, there are |
|---|
| 167 | several less obvious ones that sometimes occur. |
|---|
| 168 | <p> |
|---|
| 169 | This includes |
|---|
| 170 | an attempt to read past the end of the file. Text files need a terminating |
|---|
| 171 | new line character at the end of the file which is appended when the |
|---|
| 172 | archive destructor is invoked. Be sure that an output archive on a stream |
|---|
| 173 | is destroyed before opening an input archive on that same stream. That is, |
|---|
| 174 | rather than using something like: |
|---|
| 175 | <pre><code> |
|---|
| 176 | std::stringstream ss; |
|---|
| 177 | std::vector<V> v; |
|---|
| 178 | boost::archive::text_oarchive oa(ss); |
|---|
| 179 | oa << v; |
|---|
| 180 | boost::archive::text_iarchive ia(ss); |
|---|
| 181 | ia >> v; |
|---|
| 182 | </code></pre> |
|---|
| 183 | use |
|---|
| 184 | <pre><code> |
|---|
| 185 | std::stringstream ss; |
|---|
| 186 | std::vector<V> v; |
|---|
| 187 | { |
|---|
| 188 | boost::archive::text_oarchive oa(ss); |
|---|
| 189 | oa << v; |
|---|
| 190 | } |
|---|
| 191 | { |
|---|
| 192 | boost::archive::text_iarchive ia(ss); |
|---|
| 193 | ia >> v; |
|---|
| 194 | } |
|---|
| 195 | </code></pre> |
|---|
| 196 | <p> |
|---|
| 197 | Another one is the passing of uninitialized data. In general, the behavior |
|---|
| 198 | of the serialization library when passed uninitialized data is undefined. |
|---|
| 199 | If it can be detected, it will invoke an assertion in debug builds. |
|---|
| 200 | Otherwise, depending on the type of archive, it may pass through without |
|---|
| 201 | incident or it may result in an archive with unexpected data in it. |
|---|
| 202 | This, in turn, can result in the throwing of this exception. |
|---|
| 203 | |
|---|
| 204 | <h3><a name="invalid_class_name"><code style="white-space: normal">invalid_class_name</code></a></h3> |
|---|
| 205 | Class name length greater than the maximum permitted. Most likely cause is a corrupted |
|---|
| 206 | archive or an attempt to insert virus via buffer overrun method. |
|---|
| 207 | |
|---|
| 208 | <h3><a name="unregistered_cast"><code style="white-space: normal">unregistered_cast</code></a></h3> |
|---|
| 209 | In order to support casting between pointers of base and derived classes |
|---|
| 210 | at runtime, a collection of legitimate conversions is maintained by the system. |
|---|
| 211 | Normally this collection is maintained without any explicit action |
|---|
| 212 | on the part of the user of the library. However, there are special cases |
|---|
| 213 | where this might have to be done explicitly and could be overlooked. This |
|---|
| 214 | is described in <a href="serialization.html#runtimecasting">Runtime Casting</a>. |
|---|
| 215 | This exception is thrown if an attempt is made to convert between two pointers |
|---|
| 216 | whose relationship has not been registered, |
|---|
| 217 | |
|---|
| 218 | <h3><a name="xml_archive_parsing_error"><code style="white-space: normal">xml_archive_parsing_error</code></a></h3> |
|---|
| 219 | The XML generated by the serialization process is intimately coupled to the |
|---|
| 220 | C++ class structure, relationships between objects and the serialization |
|---|
| 221 | specifications. If these become out of sync in any way, the XML may not map |
|---|
| 222 | to the loading serialization and this exception might be thrown. This might |
|---|
| 223 | occur for one of the following reasons: |
|---|
| 224 | <ul> |
|---|
| 225 | <li>The archive has been edited outside the serialization system. This might |
|---|
| 226 | be possible if only the data is changed and not the XML attributes and nesting |
|---|
| 227 | structure is left unaltered. But any other editing is likely to render the |
|---|
| 228 | archive unreadable by the serialization library. |
|---|
| 229 | <li>The serialization has been altered and an archive generated by the old |
|---|
| 230 | code is being read. That is, versioning has not been properly employed to |
|---|
| 231 | properly deserialize previously created archives. |
|---|
| 232 | </ul> |
|---|
| 233 | |
|---|
| 234 | <h3><a name="xml_archive_tag_mismatch"><code style="white-space: normal">xml_archive_tag_mismatch</code></a></h3> |
|---|
| 235 | This exception will be thrown if the start or end tag of and XML element doesn't match |
|---|
| 236 | the name specified for the object in the program. |
|---|
| 237 | |
|---|
| 238 | <h3><a name="xml_archive_tag_name_error"><code style="white-space: normal">xml_archive_tag_name_error</code></a></h3> |
|---|
| 239 | This exception will be thrown if the tag name contains invalid characters. Valid characters |
|---|
| 240 | for an XML tag are: upper and lower case letters, digits, and the following punctuation: .(period), |
|---|
| 241 | _(underscore), :(colon), and -(hyphen). |
|---|
| 242 | |
|---|
| 243 | <hr> |
|---|
| 244 | <p><i>© Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004. |
|---|
| 245 | Distributed under the Boost Software License, Version 1.0. (See |
|---|
| 246 | accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) |
|---|
| 247 | </i></p> |
|---|
| 248 | </body> |
|---|
| 249 | </html> |
|---|
