source/ps/DllLoader.h

   1 /* Copyright (C) 2023 Wildfire Games.
   2  * This file is part of 0 A.D.
   3  *
   4  * 0 A.D. is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation, either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * 0 A.D. is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with 0 A.D.  If not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 #ifndef INCLUDED_DLLLOADER
  19 #define INCLUDED_DLLLOADER
  20
  21 #include "ps/Errors.h"
  22 #include "ps/CLogger.h"
  23 #include "ps/CStr.h"
  24
  25 ERROR_GROUP(DllLoader);
  26 ERROR_TYPE(DllLoader, DllNotLoaded);
  27 ERROR_TYPE(DllLoader, SymbolNotFound);
  28
  29 class DllLoader
  30 {
  31 public:
  32         /**
  33          * Prepare the DLL loader. Does no actual work.
  34          *
  35          * @param name base name of the library (from which we'll derive
  36          *  "name.dll", "libname_dbg.so", etc). Pointer must remain valid for
  37          *  this object's lifetime (which is fine if you just use a string literal).
  38          * @param loadErrorLogMethod Allows to set the CLogger log level that is
  39          *  used when the DllLoader reports loading errors.
  40          */
  41         DllLoader(const char* name, CLogger::ELogMethod loadErrorLogMethod = CLogger::Error);
  42
  43         ~DllLoader();
  44
  45         /**
  46          * Attempt to load and initialise the library, if not already. Can be harmlessly
  47          * called multiple times. Returns false if unsuccessful.
  48          */
  49         bool LoadDLL();
  50
  51         /**
  52          * Check whether the library has been loaded successfully. Returns false
  53          * before {@link #LoadDLL} has been called; otherwise returns the same as
  54          * LoadDLL did.
  55          */
  56         bool IsLoaded() const;
  57
  58         /**
  59          * Unload the library, if it has been loaded already. (Usually not needed,
  60          * since the destructor will unload it.)
  61          */
  62         void Unload();
  63
  64         /**
  65          * Attempt to load a named symbol from the library. If {@link #IsLoaded} is
  66          * false, throws PSERROR_DllLoader_DllNotLoaded. If it cannot load the
  67          * symbol, throws PSERROR_DllLoader_SymbolNotFound. In both cases, sets fptr
  68          * to NULL. Otherwise, fptr is set to point to the loaded function.
  69          *
  70          * @throws PSERROR_DllLoader
  71          */
  72         template <typename T>
  73         void LoadSymbol(const char* name, T& fptr) const;
  74
  75         /**
  76          * Override the build-time setting of the directory to search for libraries.
  77          */
  78         static void OverrideLibdir(const char* libdir);
  79
  80         static CStr GenerateFilename(const CStr& name, const CStr& suffix, const CStr& extension);
  81
  82 private:
  83         // Typeless version - the public LoadSymbol hides the slightly ugly
  84         // casting from users.
  85         void LoadSymbolInternal(const char* name, void** fptr) const;
  86
  87         void LogLoadError(const char* errors);
  88
  89         const char* m_Name;
  90         void* m_Handle;
  91         CLogger::ELogMethod m_LoadErrorLogMethod;
  92 };
  93
  94 template <typename T>
  95 void DllLoader::LoadSymbol(const char* name, T& fptr) const
  96 {
  97         LoadSymbolInternal(name, (void**)&fptr);
  98 }
  99
 100 #endif // INCLUDED_DLLLOADER