ACE/ace/DLL.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    DLL.h
   6  *
   7  *  @author Kirthika Parameswaran <kirthika@cs.wustl.edu>
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_DLL_H
  12 #define ACE_DLL_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include /**/ "ace/ACE_export.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 #include "ace/Global_Macros.h"
  22 #include "ace/os_include/os_dlfcn.h"
  23 #include "ace/SString.h"
  24
  25 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  26
  27 class ACE_DLL_Handle;
  28
  29 /**
  30  * @class ACE_DLL
  31  *
  32  * @brief Provides an abstract interface for handling various DLL
  33  * operations.
  34  *
  35  * This class is a wrapper over the various methods for utilizing
  36  * a dynamically linked library (DLL), which is called a shared
  37  * library on some platforms.  Operations @c open(), @c close(), and
  38  * @c symbol() have been implemented to help opening/closing and
  39  * extracting symbol information from a DLL, respectively.
  40  */
  41 class ACE_Export ACE_DLL
  42 {
  43 public:
  44   /**
  45    * Default constructor.  By default, the close() operation on the
  46    * object will be invoked before it is destroyed.
  47    * @param close_handle_on_destruction  Indicates whether or not the
  48    *        close() method will be called to close an open DLL when this
  49    *        object is destroyed. By default, close() will be called.
  50    *        Set this parameter to false for situations where the DLL's lifetime
  51    *        is controlled in a scope other than that of this ACE_DLL object.
  52    *        For example, termination by ACE_DLL_Manager via ACE::fini().
  53    */
  54   explicit ACE_DLL (bool close_handle_on_destruction = true);
  55
  56   /// Allow assignment
  57   ACE_DLL& operator= (const ACE_DLL &rhs);
  58
  59
  60   /**
  61    * This constructor performs the actions of open() during construction.
  62    * @param dll_name  The name or path of the DLL to load.
  63    * @param open_mode  Flags to alter the actions taken when loading the DLL.
  64    *        The possible values are:
  65    *        @li @c RTLD_LAZY (this the default): loads identifier symbols but
  66    *            not the symbols for functions, which are loaded dynamically
  67    *            on-demand.
  68    *        @li @c RTLD_NOW: performs all necessary relocations when
  69    *            @a dll_name is first loaded
  70    *        @li RTLD_GLOBAL: makes symbols available for relocation
  71    *            processing of any other DLLs.
  72    * @param close_handle_on_destruction  Indicates whether or not the
  73    *        close() method will be called to close an open DLL when this
  74    *        object is destroyed. By default, close() will be called.
  75    *        Set this parameter to 0 for situations where the DLL's lifetime
  76    *        is controlled in a scope other than that of this ACE_DLL object.
  77    *        For example, termination by ACE_DLL_Manager via ACE::fini().
  78    */
  79   explicit ACE_DLL (const ACE_TCHAR *dll_name,
  80                     int open_mode = ACE_DEFAULT_SHLIB_MODE,
  81                     bool close_handle_on_destruction = true);
  82
  83   /// Copy constructor.
  84   ACE_DLL (const ACE_DLL &);
  85
  86   /**
  87    * This method opens and dynamically links a specified DLL.
  88    * @param dll_name  The filename or path of the DLL to load. ACE will
  89    *        attempt to apply the platform's standard library/DLL prefixes
  90    *        and suffixes, allowing a simple, unadorned name to be passed
  91    *        regardless of platform. The set of name transforms is listed
  92    *        below. A @i decorator is a platform's name designator for a debug
  93    *        vs release build. For example, on Windows it is usually "d".
  94    *        @li Prefix + name + decorator + suffix
  95    *        @li Prefix + name + suffix
  96    *        @li Name + decorator + suffix
  97    *        @li Name + suffix
  98    *        @li Name
  99    *        Note that the transforms with @i decorator will be avoided if
 100    *        ACE is built with the @c ACE_DISABLE_DEBUG_DLL_CHECK config macro.
 101    *
 102    *        @Note There is another mode for locating library/DLL files that
 103    *        was used in old versions of ACE. The alternate method builds
 104    *        more combinations of pathname by combining the names transforms
 105    *        above with locations listed in the platform's standard "path"
 106    *        locations (e.g., @c LD_LIBRARY_PATH). It can be enabled by building
 107    *        ACE with the @c ACE_MUST_HELP_DLOPEN_SEARCH_PATH config macro.
 108    *        Use of this option is discouraged since it avoids the standard
 109    *        platform search options and security mechanisms.
 110    *
 111    * @param open_mode  Flags to alter the actions taken when loading the DLL.
 112    *        The possible values are:
 113    *        @li @c RTLD_LAZY (this the default): loads identifier symbols but
 114    *            not the symbols for functions, which are loaded dynamically
 115    *            on demand.
 116    *        @li @c RTLD_NOW: performs all necessary relocations when
 117    *            @a dll_name is first loaded
 118    *        @li @c RTLD_GLOBAL: makes symbols available for relocation
 119    *            processing of any other DLLs.
 120    * @param close_handle_on_destruction  Indicates whether or not the
 121    *        close() method will be called to close an open DLL when this
 122    *        object is destroyed. By default, close() will be called.
 123    *        Set this parameter to 0 for situations where the DLL's lifetime
 124    *        is controlled in a scope other than that of this ACE_DLL object.
 125    *        For example, termination by ACE_DLL_Manager via ACE::fini().
 126    * @retval -1 On failure
 127    * @retval 0 On success.
 128    */
 129   int open (const ACE_TCHAR *dll_name,
 130             int open_mode = ACE_DEFAULT_SHLIB_MODE,
 131             bool close_handle_on_destruction = true);
 132
 133   /// Call to close the DLL object.
 134   int close (void);
 135
 136   /**
 137    * Called when the DLL object is destroyed -- invokes close() if the
 138    * @a close_handle_on_destruction flag was set to non-zero in the
 139    * constructor or open() method.
 140    */
 141   ~ACE_DLL (void);
 142
 143   /**
 144    * Look up a named symbol in the DLL. DLL must be successfully opened
 145    * before calling symbol().
 146    * @param symbol_name The symbol name to look up.
 147    * @param ignore_errors If set to 1, allows you to probe a dll without
 148    *        generating error messages in the log.  Handy for determining
 149    *        the capabilities of a library.
 150    * @return Returns the value of @a symbol_name if it is a valid symbol
 151    *        in the DLL. Otherwise, returns 0.
 152    */
 153   void *symbol (const ACE_TCHAR *symbol_name, int ignore_errors = 0);
 154
 155   /// Returns a pointer to a string explaining that an error occurred.  You
 156   /// will need to consult the error log for the actual error string
 157   /// returned by the OS.
 158   ACE_TCHAR *error (void) const;
 159
 160   /**
 161    * Return the handle to the caller.  If @a become_owner is true then
 162    * caller assumes ownership of the handle and the ACE_DLL object
 163    * won't call close() when it goes out of scope, even if
 164    * @c close_handle_on_destruction is set.
 165    */
 166   ACE_SHLIB_HANDLE get_handle (bool become_owner = false) const;
 167
 168   /// Set the handle for the DLL object. By default, the close()
 169   /// operation on / the object will be invoked before it is destroyed.
 170   int set_handle (ACE_SHLIB_HANDLE handle,
 171                   bool close_handle_on_destruction = true);
 172
 173 private:
 174   int open_i (const ACE_TCHAR *dll_name,
 175               int open_mode = ACE_DEFAULT_SHLIB_MODE,
 176               bool close_handle_on_destruction = true,
 177               ACE_SHLIB_HANDLE handle = 0);
 178
 179
 180 public:
 181   /// Open mode.
 182   int open_mode_;
 183
 184   /// Keep track of the name of the loaded dll, so it can be used
 185   /// to remove framework components, singletons that live in the dll,
 186   /// prior to unloading the dll in the close() method.
 187   ACE_TCHAR *dll_name_;
 188
 189   /// This flag keeps track of whether we should close the handle
 190   /// automatically when the object is destroyed.
 191   bool close_handle_on_destruction_;
 192
 193   ACE_DLL_Handle *dll_handle_;
 194
 195   /// Flag to record if the last operation had an error.
 196   bool error_;
 197
 198   /// Any error messages encountered during last operation.
 199   ACE_TString errmsg_;
 200 };
 201
 202 ACE_END_VERSIONED_NAMESPACE_DECL
 203
 204 #include /**/ "ace/post.h"
 205 #endif /* ACE_DLL_H */