new home directory
[feisty_meow.git] / nucleus / library / versions / version_checker.h
1 #ifndef VERSION_CHECKER_CLASS
2 #define VERSION_CHECKER_CLASS
3
4 /*****************************************************************************\
5 *                                                                             *
6 *  Name   : check_version                                                     *
7 *  Author : Chris Koeritz                                                     *
8 *                                                                             *
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 \*****************************************************************************/
17
18 #include <basis/astring.h>
19 #include <basis/contracts.h>
20 #include <structures/version_record.h>
21
22 namespace versions {
23
24 //! Provides version checking for shared libraries.
25
26 class version_checker : public virtual basis::root_object
27 {
28 public:
29   version_checker(const basis::astring &library_file_name, const structures::version &expected,
30           const basis::astring &version_complaint);
31     //!< Constructs a checking object and ensures the version is appropriate.
32     /*!< the version checking (a call to the good_version() function) will
33     succeed if the library with the "library_file_name" (such as
34     "basis32.dll") has the "expected" version.  the simplest way to check
35     if the version is correct is probably similar to: @code
36       if (!version_checker("my.dll", version(1.2.3.4)).good_version()) {
37         ...program exit or version failure management...
38       } @endcode
39     the "version_complaint" is the message that will be displayed on a
40     failure in version checking (with noisy mode enabled).  it should
41     describe that a version failure occurred and include contact information
42     for the customer to get the most recent versions.  for example: @code
43     astring version_grievance = "Please contact Floobert Corporation for "
44         "the latest DLL and Executable files (http://www.floobert.com).";
45     @endcode */
46
47   virtual ~version_checker();  //!< Destructor releases any resources.
48
49   bool good_version() const;
50     //!< Performs the actual version check.
51     /*!< If the version check is unsuccessful, then a message that
52     describes the problem is shown to the user and false is returned.
53     NOTE: the version check will also fail if the version information
54     structure cannot be found for that library. */
55
56   static basis::astring module_name(const void *module_handle);
57     //!< returns the module name where this object resides; only sensible on win32.
58
59   // base requirements.
60   DEFINE_CLASS_NAME("version_checker");
61   basis::astring text_form() const;
62
63   static bool loaded(const basis::astring &library_file_name);
64     //!< returns true if the "library_file_name" is currently loaded.
65   static void *get_handle(const basis::astring &library_file_name);
66     //!< retrieves the module handle for the "library_file_name".
67     /*!< This returns zero if the library cannot be located.  the returned
68     pointer wraps a win32 HMODULE currently, or it is meaningless. */
69   static basis::astring get_name(const void *to_find);
70     //!< returns the name of the HMODULE specified by "to_find".
71     /*!< If that handle cannot be located, then an empty string is returned. */
72
73   static structures::version retrieve_version(const basis::astring &pathname);
74     //!< Returns the version given a "pathname" to the DLL or EXE file.
75     /*!< If the directory component is not included, then the search path
76     will be used. */
77
78   static bool get_record(const basis::astring &pathname, structures::version_record &to_fill);
79     //!< Retrieves a version record for the file at "pathname".
80     /*!< Returns the full version record found for a given "pathname" to
81     the DLL or EXE file in the record "to_fill".  if the directory component
82     of the path is not included, then the search path will be used.  false is
83     returned if some piece of information could not be located; this does not
84     necessarily indicate a total failure of the retrieval. */
85
86   static bool retrieve_version_info(const basis::astring &filename,
87           basis::byte_array &to_fill);
88     //!< Retrieves the version info for the "filename" into the array "to_fill".
89
90   static bool get_language(basis::byte_array &version_chunk, basis::un_short &high,
91           basis::un_short &low);
92     //!< Gets the language identifier out of the "version_chunk".
93     /*!< Returns true if the language identifier for the dll's version chunk
94     could be stored in "high" and "low".  This is a win32-only method. */
95
96   void complain_wrong_version(const basis::astring &library_file_name,
97           const structures::version &expected_version,
98           const structures::version &version_found) const;
99     //!< Reports that the file has the wrong version.
100
101   void complain_cannot_load(const basis::astring &library_file_name) const;
102     //!< Reports that the dll could not be loaded.
103
104 private:
105   basis::astring *_library_file_name;
106   structures::version *_expected_version;
107   basis::astring *_version_complaint;
108
109   // forbidden.
110   version_checker(const version_checker &);
111   version_checker &operator =(const version_checker &);
112 };
113
114 } //namespace.
115
116 #endif
117