Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages | Search for 

ACE_DLL Class Reference

Provides an abstract interface for handling various DLL operations. More...

#include <DLL.h>

Collaboration diagram for ACE_DLL:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 ACE_DLL (int close_handle_on_destruction=1)
ACE_DLL & operator= (const ACE_DLL &rhs)
 Allow assignment.

 ACE_DLL (const ACE_TCHAR *dll_name, int open_mode=ACE_DEFAULT_SHLIB_MODE, int close_handle_on_destruction=1)
 ACE_DLL (const ACE_DLL &)
 Copy constructor.

int open (const ACE_TCHAR *dll_name, int open_mode=ACE_DEFAULT_SHLIB_MODE, int close_handle_on_destruction=1)
int close (void)
 Call to close the DLL object.

 ~ACE_DLL (void)
void * symbol (const ACE_TCHAR *symbol_name, int ignore_errors=0)
ACE_TCHAR * error (void) const
ACE_SHLIB_HANDLE get_handle (int become_owner=0) const
int set_handle (ACE_SHLIB_HANDLE handle, int close_handle_on_destruction=1)
 Set the handle for the DLL object. By default, the close().


Public Attributes

int open_mode_
 Open mode.

ACE_TCHAR * dll_name_
int close_handle_on_destruction_
ACE_DLL_Handle * dll_handle_
int error_
 Flag to record if the last operation had an error.


Private Member Functions

int open_i (const ACE_TCHAR *dll_name, int open_mode=ACE_DEFAULT_SHLIB_MODE, int close_handle_on_destruction=1, ACE_SHLIB_HANDLE handle=0)

Detailed Description

Provides an abstract interface for handling various DLL operations.

This class is a wrapper over the various methods for utilizing a dynamically linked library (DLL), which is called a shared library on some platforms. Operations open(), close(), and symbol() have been implemented to help opening/closing and extracting symbol information from a DLL, respectively.

Definition at line 42 of file DLL.h.

Constructor & Destructor Documentation

ACE_BEGIN_VERSIONED_NAMESPACE_DECL ACE_DLL::ACE_DLL (  int  close_handle_on_destruction = 1  )  [explicit]
 

Default constructor. By default, the close() operation on the object will be invoked before it is destroyed.

Parameters:
close_handle_on_destruction Indicates whether or not the close() method will be called to close an open DLL when this object is destroyed. By default, close() will be called. Set this parameter to 0 for situations where the DLL's lifetime is controlled in a scope other than that of this ACE_DLL object. For example, termination by ACE_DLL_Manager via ACE::fini().

Definition at line 21 of file DLL.cpp.

References ACE_TRACE. 

00022   : open_mode_ (0),
00023     dll_name_ (0),
00024     close_handle_on_destruction_ (close_handle_on_destruction),
00025     dll_handle_ (0),
00026     error_ (0)
00027 {
00028   ACE_TRACE ("ACE_DLL::ACE_DLL (int)");
00029 }

ACE_DLL::ACE_DLL (  const ACE_TCHAR *  dll_name,
int  open_mode = ACE_DEFAULT_SHLIB_MODE,
int  close_handle_on_destruction = 1
)  [explicit]
 

This constructor performs the actions of open() during construction.

Parameters:
dll_name The name or path of the DLL to load.
open_mode Flags to alter the actions taken when loading the DLL. The possible values are:
  • RTLD_LAZY (this the default): loads identifier symbols but not the symbols for functions, which are loaded dynamically on-demand.
  • RTLD_NOW: performs all necessary relocations when dll_name is first loaded
  • RTLD_GLOBAL: makes symbols available for relocation processing of any other DLLs.
close_handle_on_destruction Indicates whether or not the close() method will be called to close an open DLL when this object is destroyed. By default, close() will be called. Set this parameter to 0 for situations where the DLL's lifetime is controlled in a scope other than that of this ACE_DLL object. For example, termination by ACE_DLL_Manager via ACE::fini().

Definition at line 74 of file DLL.cpp.

References ACE_ERROR, ACE_TCHAR, ACE_TEXT, ACE_TRACE, ACE::debug(), LM_ERROR, and open(). 

00077   : open_mode_ (open_mode),
00078     dll_name_ (0),
00079     close_handle_on_destruction_ (close_handle_on_destruction),
00080     dll_handle_ (0),
00081     error_ (0)
00082 {
00083   ACE_TRACE ("ACE_DLL::ACE_DLL");
00084 
00085   if (this->open (dll_name, this->open_mode_, close_handle_on_destruction) != 0
00086       && ACE::debug ())
00087     ACE_ERROR ((LM_ERROR,
00088                 ACE_TEXT ("ACE_DLL::open: error calling open: %s\n"),
00089                 this->error ()));
00090 }

ACE_DLL::ACE_DLL (  const ACE_DLL &   ) 
 

Copy constructor.

Definition at line 31 of file DLL.cpp.

References ACE_ERROR, ACE_TEXT, ACE_TRACE, close_handle_on_destruction_, ACE::debug(), dll_name_, LM_ERROR, open(), and open_mode_. 

00032   : open_mode_ (0),
00033     dll_name_ (0),
00034     close_handle_on_destruction_ (0),
00035     dll_handle_ (0),
00036     error_ (0)
00037 {
00038   ACE_TRACE ("ACE_DLL::ACE_DLL (const ACE_DLL &)");
00039 
00040   if (rhs.dll_name_
00041       // This will automatically up the refcount.
00042       && this->open (rhs.dll_name_,
00043                      rhs.open_mode_,
00044                      rhs.close_handle_on_destruction_) != 0
00045       && ACE::debug ())
00046     ACE_ERROR ((LM_ERROR,
00047     ACE_TEXT ("ACE_DLL::copy_ctor: error: %s\n"),
00048     this->error ()));
00049 }

ACE_DLL::~ACE_DLL (  void   ) 
 

Called when the DLL object is destroyed -- invokes close() if the close_handle_on_destruction flag was set to non-zero in the constructor or open() method.

Definition at line 96 of file DLL.cpp.

References ACE_TRACE, close(), and dll_name_. 

00097 {
00098   ACE_TRACE ("ACE_DLL::~ACE_DLL");
00099 
00100   this->close ();
00101 
00102   // Normally delete()d in ACE_DLL::close().  However, that may not
00103   // occur if full ACE_DLL initialization is interrupted due to errors
00104   // (e.g. attempting to open a DSO/DLL that does not exist).  Make
00105   // sure this->dll_name_ is deallocated.
00106   delete [] this->dll_name_;
00107 }

Member Function Documentation

int ACE_DLL::close (  void   ) 
 

Call to close the DLL object.

Definition at line 198 of file DLL.cpp.

References ACE_TRACE, ACE_DLL_Manager::close_dll(), close_handle_on_destruction_, dll_handle_, dll_name_, error_, and ACE_DLL_Manager::instance().

Referenced by ACE_Service_Type::fini(), open_i(), and ~ACE_DLL(). 

00199 {
00200   ACE_TRACE ("ACE_DLL::close");
00201 
00202   int retval = 0;
00203 
00204   if (this->dll_handle_
00205       && this->close_handle_on_destruction_
00206       && this->dll_name_
00207       && (retval = ACE_DLL_Manager::instance ()->close_dll (this->dll_name_)) != 0)
00208     this->error_ = 1;
00209 
00210   // Even if close_dll() failed, go ahead and cleanup.
00211   this->dll_handle_ = 0;
00212   delete [] this->dll_name_;
00213   this->dll_name_ = 0;
00214   this->close_handle_on_destruction_ = 0;
00215 
00216   return retval;
00217 }

ACE_TCHAR * ACE_DLL::error (  void   )  const
 

Returns a pointer to a string explaining that an error occured. You will need to consult the error log for the actual error string returned by the OS.

Definition at line 222 of file DLL.cpp.

References ACE_TEXT, ACE_TRACE, and error_. 

00223 {
00224   ACE_TRACE ("ACE_DLL::error");
00225   if (this->error_)
00226     return
00227       const_cast<ACE_TCHAR *> (ACE_TEXT ("Error: check log for details."));
00228 
00229   return 0;
00230 }

ACE_SHLIB_HANDLE ACE_DLL::get_handle (  int  become_owner = 0  )  const
 

Return the handle to the caller. If become_owner is non-0 then caller assumes ownership of the handle and the ACE_DLL object won't call close() when it goes out of scope, even if is set.

Definition at line 237 of file DLL.cpp.

References ACE_SHLIB_HANDLE, ACE_SHLIB_INVALID_HANDLE, ACE_TRACE, dll_handle_, and ACE_DLL_Handle::get_handle().

Referenced by ACE_Service_Repository::relocate_i(). 

00238 {
00239   ACE_TRACE ("ACE_DLL::get_handle");
00240 
00241   ACE_SHLIB_HANDLE handle = ACE_SHLIB_INVALID_HANDLE;
00242 
00243   if (this->dll_handle_)
00244     handle = this->dll_handle_->get_handle (become_owner);
00245 
00246   return handle;
00247 }

int ACE_DLL::open (  const ACE_TCHAR *  dll_name,
int  open_mode = ACE_DEFAULT_SHLIB_MODE,
int  close_handle_on_destruction = 1
) 
 

This method opens and dynamically links a specified DLL.

Parameters:
dll_name The filename or path of the DLL to load. If a filename is given to open(), the ACE::ldfind() is used to locate DLLs via the following algorithms: (1) DLL filename expansion: ACE::ldfind() determines the name of the DLL by adding the appropriate prefix and suffix, e.g., it adds the lib prefix and .so suffix for Solaris and the .dll suffix for Windows and (2) DLL search path: ACE::ldfind() will also search for the designated DLL using the platform's DLL search path environment variable, e.g., it searches for DLLs using LD_LIBRARY_PATH on many UNIX systems and PATH on Windows.
open_mode Flags to alter the actions taken when loading the DLL. The possible values are:
  • RTLD_LAZY (this the default): loads identifier symbols but not the symbols for functions, which are loaded dynamically on-demand.
  • RTLD_NOW: performs all necessary relocations when dll_name is first loaded
  • RTLD_GLOBAL: makes symbols available for relocation processing of any other DLLs.
close_handle_on_destruction Indicates whether or not the close() method will be called to close an open DLL when this object is destroyed. By default, close() will be called. Set this parameter to 0 for situations where the DLL's lifetime is controlled in a scope other than that of this ACE_DLL object. For example, termination by ACE_DLL_Manager via ACE::fini().
Return values:
-1 On failure
0 On success.

Definition at line 121 of file DLL.cpp.

References ACE_TCHAR, ACE_TRACE, and open_i().

Referenced by ACE_DLL(). 

00124 {
00125   ACE_TRACE ("ACE_DLL::open");
00126 
00127   return open_i (dll_filename, open_mode, close_handle_on_destruction);
00128 }

int ACE_DLL::open_i (  const ACE_TCHAR *  dll_name,
int  open_mode = ACE_DEFAULT_SHLIB_MODE,
int  close_handle_on_destruction = 1,
ACE_SHLIB_HANDLE  handle = 0
)  [private]
 

Definition at line 131 of file DLL.cpp.

References ACE_ERROR, ACE_SHLIB_HANDLE, ACE_TCHAR, ACE_TEXT, ACE_TRACE, close(), close_handle_on_destruction_, ACE::debug(), dll_handle_, dll_name_, error_, ACE_DLL_Manager::instance(), LM_ERROR, ACE_DLL_Manager::open_dll(), open_mode_, ACE_OS::strcmp(), and ACE::strnew().

Referenced by open(), and set_handle(). 

00135 {
00136   ACE_TRACE ("ACE_DLL::open_i");
00137 
00138   this->error_ = 0;
00139 
00140   if (!dll_filename)
00141     {
00142       if (ACE::debug ())
00143         ACE_ERROR ((LM_ERROR,
00144                     ACE_TEXT ("ACE_DLL::open_i: dll_name is %s\n"),
00145                     this->dll_name_ == 0 ? ACE_TEXT ("(null)")
00146         : this->dll_name_));
00147       return -1;
00148     }
00149 
00150   if (this->dll_handle_)
00151     {
00152       // If we have a good handle and its the same name, just return.
00153       if (ACE_OS::strcmp (this->dll_name_, dll_filename) == 0)
00154         return 0;
00155       else
00156         this->close ();
00157     }
00158 
00159   if (!this->dll_name_)
00160     this->dll_name_ = ACE::strnew (dll_filename);
00161 
00162   this->open_mode_ = open_mode;
00163   this->close_handle_on_destruction_ = close_handle_on_destruction;
00164 
00165   this->dll_handle_ = ACE_DLL_Manager::instance()->open_dll (this->dll_name_,
00166                                                              this->open_mode_,
00167                                                              handle);
00168 
00169   if (!this->dll_handle_)
00170     this->error_ = 1;
00171 
00172   return this->error_ ? -1 : 0;
00173 }

ACE_DLL & ACE_DLL::operator= (  const ACE_DLL &  rhs  ) 
 

Allow assignment.

Definition at line 54 of file DLL.cpp.

References ACE_TRACE, close_handle_on_destruction_, dll_handle_, dll_name_, error_, and open_mode_. 

00055 {
00056   ACE_TRACE ("ACE_DLL::operator= (const ACE_DLL &)");
00057 
00058   ACE_DLL tmp (rhs);
00059 
00060   std::swap (this->open_mode_, tmp.open_mode_);
00061   std::swap (this->dll_name_, tmp.dll_name_);
00062   std::swap (this->close_handle_on_destruction_,
00063              tmp.close_handle_on_destruction_);
00064   std::swap (this->dll_handle_, tmp.dll_handle_);
00065   std::swap (this->error_, tmp.error_);
00066 
00067   return *this;
00068 }

int ACE_DLL::set_handle (  ACE_SHLIB_HANDLE  handle,
int  close_handle_on_destruction = 1
) 
 

Set the handle for the DLL object. By default, the close().

Definition at line 253 of file DLL.cpp.

References ACE_SHLIB_HANDLE, ACE_TCHAR, ACE_TRACE, ACE_UNIQUE_NAME_LEN, open_i(), and ACE_OS::unique_name().

Referenced by ACE_Service_Type::ACE_Service_Type(). 

00255 {
00256   ACE_TRACE ("ACE_DLL::set_handle");
00257 
00258   // Create a unique name.  Note that this name is only quaranteed
00259   // to be unique for the life of this object.
00260   ACE_TCHAR temp[ACE_UNIQUE_NAME_LEN];
00261   ACE_OS::unique_name (this, temp, ACE_UNIQUE_NAME_LEN);
00262 
00263   return this->open_i (temp, 1, close_handle_on_destruction, handle);
00264 }

void * ACE_DLL::symbol (  const ACE_TCHAR *  symbol_name,
int  ignore_errors = 0
) 
 

Look up a named symbol in the DLL. DLL must be successfully opened before calling symbol().

Parameters:
symbol_name The symbol name to look up.
ignore_errors If set to 1, allows you to probe a dll without generating error messages in the log. Handy for determining the capabilities of a library.
Returns:
Returns the value of symbol_name if it is a valid symbol in the DLL. Otherwise, returns 0.

Definition at line 178 of file DLL.cpp.

References ACE_TCHAR, ACE_TRACE, dll_handle_, error_, and ACE_DLL_Handle::symbol(). 

00179 {
00180   ACE_TRACE ("ACE_DLL::symbol");
00181 
00182   this->error_ = 0;
00183 
00184   void *sym = 0;
00185   if (this->dll_handle_)
00186     sym = this->dll_handle_->symbol (sym_name, ignore_errors);
00187 
00188   if (!sym)
00189     this->error_ = 1;
00190 
00191   return sym;
00192 }

Member Data Documentation

int ACE_DLL::close_handle_on_destruction_
 

This flag keeps track of whether we should close the handle automatically when the object is destroyed.

Definition at line 184 of file DLL.h.

Referenced by ACE_DLL(), close(), open_i(), and operator=().

ACE_DLL_Handle* ACE_DLL::dll_handle_
 

Definition at line 186 of file DLL.h.

Referenced by close(), get_handle(), open_i(), operator=(), and symbol().

ACE_TCHAR* ACE_DLL::dll_name_
 

Keep track of the name of the loaded dll, so it can be used to remove framework components, singletons that live in the dll, prior to unloading the dll in the close() method.

Definition at line 180 of file DLL.h.

Referenced by ACE_DLL(), close(), open_i(), operator=(), ACE_Service_Gestalt::process_directive_i(), and ~ACE_DLL().

int ACE_DLL::error_
 

Flag to record if the last operation had an error.

Definition at line 189 of file DLL.h.

Referenced by close(), error(), open_i(), operator=(), and symbol().

int ACE_DLL::open_mode_
 

Open mode.

Definition at line 175 of file DLL.h.

Referenced by ACE_DLL(), open_i(), and operator=().

The documentation for this class was generated from the following files:
Generated on Sun Jan 27 12:54:27 2008 for ACE by doxygen 1.3.6