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