Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

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 Methods

 ACE_DLL (int close_on_destruction=1)
 Default constructor. By default, the close() operation on the object will be invoked before it is destroyed. More...

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

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

 ~ACE_DLL (void)
void * symbol (const ACE_TCHAR *symbol_name, int ignore_errors=0)
 If symbol_name is in the symbol table of the DLL a pointer to the symbol_name is returned. Otherwise, returns 0. Setting ignore_errors = 1 allows you to probe a dll without generating error messages in the log. Handy for determining the capabilities of a library. More...

ACE_TCHAR * 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. More...

ACE_SHLIB_HANDLE get_handle (int become_owner=0) const
int set_handle (ACE_SHLIB_HANDLE handle, int close_on_destruction=1)
 Set the handle for the DLL object. By default, the close() operation on the object will be invoked before it is destroyed. More...


Private Methods

int open_i (const ACE_TCHAR *dll_name, int open_mode=ACE_DEFAULT_SHLIB_MODE, int close_on_destruction=1, ACE_SHLIB_HANDLE handle=0)
void operator= (const ACE_DLL &)

Private Attributes

int open_mode_
 Open mode. More...

ACE_TCHAR * 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. More...

int close_on_destruction_
 This flag keeps track of whether we should close the handle automatically when the destructor runs. More...

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

Detailed Description

Provides an abstract interface for handling various DLL operations.

This class is an 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 38 of file DLL.h.

Constructor & Destructor Documentation

ACE_DLL::ACE_DLL (  int    close_on_destruction = 1 ) 
 

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

Definition at line 16 of file DLL.cpp.

References ACE_TRACE. 

00017   : open_mode_ (0),
00018     dll_name_ (0),
00019     close_on_destruction_ (close_on_destruction),
00020     dll_handle_ (0),
00021     error_ (0)
00022 {
00023   ACE_TRACE ("ACE_DLL::ACE_DLL (int)");
00024 }

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

This constructor opens and dynamically links dll_name. The default mode is <RTLD_LAZY>, which loads identifier symbols but not the symbols for functions, which are loaded dynamically on-demand. Other supported modes include: <RTLD_NOW>, which performs all necessary relocations when dll_name is first loaded and <RTLD_GLOBAL>, which makes symbols available for relocation processing of any other DLLs.

Definition at line 47 of file DLL.cpp.

References ACE_ERROR, ACE_LIB_TEXT, ACE_TCHAR, ACE_TRACE, LM_ERROR, and open. 

00050   : open_mode_ (open_mode),
00051     dll_name_ (0),
00052     close_on_destruction_ (close_on_destruction),
00053     dll_handle_ (0),
00054     error_ (0)
00055 {
00056   ACE_TRACE ("ACE_DLL::ACE_DLL");
00057 
00058   if (this->open (dll_name, this->open_mode_, close_on_destruction) != 0)
00059     ACE_ERROR ((LM_ERROR,
00060                 ACE_LIB_TEXT ("ACE_DLL::open: error calling open: %s\n"),
00061                 this->error ()));
00062 }

ACE_DLL::ACE_DLL (  const ACE_DLL &    ) 
 

Copy constructor.

Definition at line 26 of file DLL.cpp.

References ACE_ERROR, ACE_LIB_TEXT, ACE_TRACE, close_on_destruction_, dll_handle_, dll_name_, error_, LM_ERROR, open, and open_mode_. 

00027 {
00028   ACE_TRACE ("ACE_DLL::ACE_DLL (const ACE_DLL &)");
00029 
00030   // Have to do this since open() calls close()...
00031   this->dll_handle_ = 0;
00032   this->dll_name_ = 0;
00033   this->close_on_destruction_ = 1;
00034   this->error_ = 0;
00035 
00036   if (rhs.dll_name_)
00037     // This will automatically up the refcount.
00038     if (this->open (rhs.dll_name_, rhs.open_mode_, this->close_on_destruction_) != 0)
00039       ACE_ERROR ((LM_ERROR,
00040                   ACE_LIB_TEXT ("ACE_DLL::copy_ctor: error: %s\n"),
00041                   this->error ()));
00042 }

ACE_DLL::~ACE_DLL (  void    ) 
 

Called when the DLL object is destroyed -- invokes close() if the <close_on_destruction> flag is set in the constructor or open() method.

Definition at line 68 of file DLL.cpp.

References ACE_TRACE, and close. 

00069 {
00070   ACE_TRACE ("ACE_DLL::~ACE_DLL");
00071 
00072   this->close ();
00073 }

Member Function Documentation

int ACE_DLL::close (  void    ) 
 

Call to close the DLL object.

Definition at line 158 of file DLL.cpp.

References ACE_TRACE, ACE_DLL_Manager::close_dll, close_on_destruction_, dll_handle_, dll_name_, error_, and ACE_DLL_Manager::instance.

Referenced by open_i, and ~ACE_DLL. 

00159 {
00160   ACE_TRACE ("ACE_DLL::close");
00161   int retval = 0;
00162 
00163   if (this->close_on_destruction_ && this->dll_name_ &&
00164       (retval = ACE_DLL_Manager::instance ()->close_dll (this->dll_name_)) != 0)
00165     this->error_ = 1;
00166 
00167   // Even if close_dll() failed, go ahead and cleanup.
00168   this->dll_handle_ = 0;
00169   delete[] this->dll_name_;
00170   this->dll_name_ = 0;
00171   this->close_on_destruction_ = 0;
00172 
00173   return retval;
00174 }

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 179 of file DLL.cpp.

References ACE_LIB_TEXT, ACE_TCHAR, ACE_TRACE, and error_.

Referenced by ACE_Location_Node::open_dll, ACE_Function_Node::symbol, and ACE_Object_Node::symbol. 

00180 {
00181   ACE_TRACE ("ACE_DLL::error");
00182   if (this->error_)
00183     return ACE_const_cast (ACE_TCHAR *,
00184                            ACE_LIB_TEXT ("Error:  check log for details."));
00185 
00186   return 0;
00187 }

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 <close_on_destruction> is set.

Definition at line 194 of file DLL.cpp.

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

00195 {
00196   ACE_TRACE ("ACE_DLL::get_handle");
00197 
00198   ACE_SHLIB_HANDLE handle = ACE_SHLIB_INVALID_HANDLE;
00199 
00200   if (this->dll_handle_)
00201     handle = this->dll_handle_->get_handle (become_owner);
00202 
00203   return handle;
00204 }

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

This method opens and dynamically links dll_name. The default mode is <RTLD_LAZY>, which loads identifier symbols but not the symbols for functions, which are loaded dynamically on-demand. Other supported modes include: <RTLD_NOW>, which performs all necessary relocations when dll_name>is first loaded and <RTLD_GLOBAL>, which makes symbols available for relocation processing of any other DLLs.

Parameters:
dll_name  The name of the dll.
open_mode  How the dll is opened.
close_on_destruction  Close the handle in the destructor.
Return values:
-1  On failure
0  On success.

Definition at line 87 of file DLL.cpp.

References ACE_TCHAR, ACE_TRACE, and open_i.

Referenced by ACE_DLL, and ACE_Location_Node::open_dll. 

00090 {
00091   ACE_TRACE ("ACE_DLL::open");
00092 
00093   return open_i (dll_filename, open_mode, close_on_destruction);
00094 }

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

Definition at line 97 of file DLL.cpp.

References ACE_ERROR_RETURN, ACE_LIB_TEXT, ACE_SHLIB_HANDLE, ACE_TCHAR, ACE_TRACE, close, close_on_destruction_, dll_handle_, dll_name_, error_, ACE_DLL_Manager::instance, LM_ERROR, ACE_DLL_Manager::open_dll, open_mode_, ACE_OS_String::strcmp, and ACE::strnew.

Referenced by open, and set_handle. 

00101 {
00102   ACE_TRACE ("ACE_DLL::open_i");
00103 
00104   this->error_ = 0;
00105 
00106   if (!dll_filename)
00107     ACE_ERROR_RETURN ((LM_ERROR,
00108                        ACE_LIB_TEXT ("ACE_DLL::open_i: dll_name: %s\n"),
00109                        this->dll_name_),
00110                       -1);
00111 
00112   if (this->dll_handle_)
00113     {
00114       // If we have a good handle and its the same name, just return.
00115       if (ACE_OS_String::strcmp (this->dll_name_, dll_filename) == 0)
00116         return 0;
00117       else
00118         this->close ();
00119     }
00120   if (!this->dll_name_)
00121     {
00122       this->dll_name_ = ACE::strnew (dll_filename);
00123     }
00124   this->open_mode_ = open_mode;
00125   this->close_on_destruction_ = close_on_destruction;
00126 
00127   this->dll_handle_ = ACE_DLL_Manager::instance()->open_dll (this->dll_name_,
00128                                                              this->open_mode_,
00129                                                              handle);
00130 
00131   if (!this->dll_handle_)
00132     this->error_ = 1;
00133 
00134   return this->error_ ? -1 : 0;
00135 }

void ACE_DLL::operator= (  const ACE_DLL &    )  [private]
 

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

Set the handle for the DLL object. By default, the close() operation on the object will be invoked before it is destroyed.

Definition at line 210 of file DLL.cpp.

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

00212 {
00213   ACE_TRACE ("ACE_DLL::set_handle");
00214 
00215   // Create a unique name.  Note that this name is only quaranteed
00216   // to be unique for the life of this object.
00217   ACE_TCHAR temp[ACE_UNIQUE_NAME_LEN];
00218   ACE_OS::unique_name (this, temp, ACE_UNIQUE_NAME_LEN);
00219 
00220   return this->open_i (temp, 1, close_on_destruction, handle);
00221 }

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

If symbol_name is in the symbol table of the DLL a pointer to the symbol_name is returned. Otherwise, returns 0. Setting ignore_errors = 1 allows you to probe a dll without generating error messages in the log. Handy for determining the capabilities of a library.

Definition at line 140 of file DLL.cpp.

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

Referenced by ACE_Function_Node::symbol, and ACE_Object_Node::symbol. 

00141 {
00142   ACE_TRACE ("ACE_DLL::symbol");
00143 
00144   this->error_ = 0;
00145 
00146   void *sym = this->dll_handle_->symbol (sym_name, ignore_errors);
00147 
00148   if (!sym)
00149     this->error_ = 1;
00150 
00151   return sym;
00152 }

Member Data Documentation

int ACE_DLL::close_on_destruction_ [private]
 

This flag keeps track of whether we should close the handle automatically when the destructor runs.

Definition at line 133 of file DLL.h.

Referenced by ACE_DLL, close, and open_i.

ACE_DLL_Handle* ACE_DLL::dll_handle_ [private]
 

Definition at line 135 of file DLL.h.

Referenced by ACE_DLL, close, get_handle, open_i, and symbol.

ACE_TCHAR* ACE_DLL::dll_name_ [private]
 

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 129 of file DLL.h.

Referenced by ACE_DLL, close, and open_i.

int ACE_DLL::error_ [private]
 

Flag to record if the last operation had an error.

Definition at line 138 of file DLL.h.

Referenced by ACE_DLL, close, error, open_i, and symbol.

int ACE_DLL::open_mode_ [private]
 

Open mode.

Definition at line 124 of file DLL.h.

Referenced by ACE_DLL, and open_i.

The documentation for this class was generated from the following files:
Generated on Mon Jun 16 12:47:14 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002