1 #ifndef VERSION_STRUCTURE_GROUP
2 #define VERSION_STRUCTURE_GROUP
4 /*****************************************************************************\
6 * Name : version & version_record *
7 * Author : Chris Koeritz *
9 *******************************************************************************
10 * Copyright (c) 1996-$now By Author. This program is free software; you can *
11 * redistribute it and/or modify it under the terms of the GNU General Public *
12 * License as published by the Free Software Foundation; either version 2 of *
13 * the License or (at your option) any later version. This is online at: *
14 * http://www.fsf.org/copyleft/gpl.html *
15 * Please send any updates to: fred@gruntose.com *
16 \*****************************************************************************/
18 /*! @file version_record.h
19 Note that this header is tuned for forward declaration of the version
20 and version_record objects; this is a better approach than including this
21 somewhat heavy header file in other header files.
24 #include "string_array.h"
26 #include <basis/astring.h>
27 #include <basis/contracts.h>
29 namespace structures {
31 //! Holds a file's version identifier.
33 The version structures can be used in any of our components because
34 they're not platform specific. They maintain information about a file
35 that is part of the released product.
38 class version : public virtual basis::packable, public virtual basis::orderable
41 version(); //!< constructs a blank version.
43 version(const structures::string_array &version_info);
44 //!< constructs a version from a list of strings that form the components.
45 /*!< note that if a component is an empty string, it is changed to be a
48 version(const basis::astring &formatted_string);
49 //!< the version components will be parsed from the "formatted_string".
50 /*!< the version component separator is the period ('.') or the comma (',')
53 version(int major, int minor, int rev = 0, int build = 0);
54 //!< constructs a win32 style version structure from the information.
56 version(const version &to_copy);
57 //!< constructs a copy of "to_copy".
61 version &operator =(const version &to_copy);
62 //!< assigns this to the "to_copy".
64 DEFINE_CLASS_NAME("version");
66 virtual basis::astring text_form() const;
68 bool equal_to(const equalizable &to_test) const;
69 //!< compares two versions for exact equality.
70 /*!< to perform a check of win32 build compatibility, use the
71 compatible() method. */
73 bool less_than(const orderable &to_test) const;
74 //!< reports if this version is less than "to_test".
75 /*!< supplies the other operator needed for the full set of comparisons
76 (besides equality). the basis namespace provides templates for the rest
77 of the comparison operators in <basis/functions.h>. */
79 int components() const;
80 //!< reports the number of components that make up this version.
82 basis::astring get_component(int index) const;
83 //!< returns the component at the specified index.
84 /*!< note that if an entry is an empty string, then a string with zero
85 in it is returned ("0"). */
87 void set_component(int index, const basis::astring &to_set);
88 //!< sets the component at "index" to "to_set".
89 /*!< an empty string for "to_set" is turned into a zero. */
91 enum version_places { MAJOR, MINOR, REVISION, BUILD };
92 //!< these are names for the first four components of the version.
93 /*!< there may be more components than four on some platforms. */
95 enum version_style { DOTS, COMMAS, DETAILED };
96 //!< different ways that a version object can be displayed.
97 /*!< DOTS is in the form "1.2.3.4"
98 COMMAS is in the form "1, 2, 3, 4"
99 DETAILED is in the form "major 1, minor 2, ..."
102 basis::astring flex_text_form(version_style style = DOTS, int including = -1) const;
103 //!< returns a textual form of the version number.
104 /*!< the place passed in "including" specifies how much of the version
105 to print, where a negative number means all components. for example, if
106 "including" is MINOR, then only the first two components (major and minor
107 components) are printed. */
109 static version from_text(const basis::astring &to_convert);
110 //!< returns a version structure parsed from "to_convert".
112 virtual int packed_size() const;
113 virtual void pack(basis::byte_array &target) const;
114 virtual bool unpack(basis::byte_array &source);
118 // the following methods mainly help on win32 platforms, where the version
119 // components are always simple short integers. there are only ever four
120 // of these. if one adheres to that same scheme on other platforms, then
121 // these functions may be helpful. otherwise, with the mixed alphanumeric
122 // versions one sees on unix, these are not so great.
125 //!< major version number.
126 /*!< major & minor are the most significant values for a numerical version.
127 these are the familiar numbers often quoted for software products, like
128 "jubware version 8.2". */
130 //!< minor version number.
131 int v_revision() const;
133 /*!< in the hoople code and the clam system, this number is changed for
134 every new build. when two versions of a file are the same in major,
135 minor and revision numbers, then they are said to be compatible. for
136 those using this version scheme, it asserts that dll compatibility has not
137 been broken if one swaps those two files in an installation. after the
138 swap, any components that are dependent on the dll must all link properly
139 against the replacement file. when in doubt, increment the version number.
140 some folks automatically increment the revision level every week. */
143 /*!< this number is not considered important when comparing file
144 compatibility. the compatible() method always returns true if two files
145 differ only in the "build" number (rather than major, minor or revision).
146 this allows patches to be created with a newer (larger) build number, but
147 still link fine with existing dlls. since the file is distinguished by
148 more than just its time stamp, it allows changes to an installation to be
149 tracked very precisely. some folks keep a catalog of patched components
150 for each software release and index the patch details by the different
153 bool compatible(const version &that) const;
154 //!< returns true if this is compatible with "that" version on win32.
155 /*!< that means that all version components are the same except for the
156 last one, the build number. we allow the build numbers to fluctuate so
157 that patched components can be installed without causing version
161 //!< returns true if the version held here is clearly bogus.
162 /*!< this means that all four numbers are zero. */
166 static void *__global_module_handle();
167 //!< a static resource required to identify the actual win32 module that this lives in.
168 /*!< this handle is stored statically when the libraries are started up. it records
169 the handle of the module they belong to for later use in checking versions. */
171 //hmmm: storage here is still missing!
174 structures::string_array *_components; //!< our list of version components.
179 //! Holds all information about a file's versioning.
180 /*! Not all of these fields are meaningful on every platform. */
182 class version_record : public virtual basis::root_object
185 virtual ~version_record();
187 DEFINE_CLASS_NAME("version_record");
189 basis::astring text_form() const;
190 // returns a view of the fields in this record.
192 // these describe a particular file:
193 basis::astring description; // the purpose of this file.
194 version file_version; // the version number for this file.
195 basis::astring internal_name; // the internal name of the file.
196 basis::astring original_name; // name of file before possible renamings.
198 // these describe the project that the file belongs to:
199 basis::astring product_name; // the product this file belongs to.
200 version product_version; // the version of the product.
202 // these describe the creators of the file:
203 basis::astring company_name; // name of the company that created the file.
206 basis::astring copyright; // copyright info for this file.
207 basis::astring trademarks; // trademarks related to the file.
209 // extra pieces not stored in record (yet).
210 basis::astring web_address; // the location of the company on the web.