Provides an abstract interface for handling various DLL operations. More...
#include <DLL.h>
Public Member Functions | |
ACE_DLL (bool close_handle_on_destruction=true) | |
ACE_DLL & | operator= (const ACE_DLL &rhs) |
Allow assignment. | |
ACE_DLL (const ACE_TCHAR *dll_name, int open_mode=ACE_DEFAULT_SHLIB_MODE, bool close_handle_on_destruction=true) | |
ACE_DLL (const ACE_DLL &) | |
Copy constructor. | |
int | open (const ACE_TCHAR *dll_name, int open_mode=ACE_DEFAULT_SHLIB_MODE, bool close_handle_on_destruction=true) |
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, bool close_handle_on_destruction=true) |
Public Attributes | |
int | open_mode_ |
Open mode. | |
ACE_TCHAR * | dll_name_ |
bool | close_handle_on_destruction_ |
ACE_DLL_Handle * | dll_handle_ |
bool | 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, bool close_handle_on_destruction=true, ACE_SHLIB_HANDLE handle=0) |
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.
ACE_DLL::ACE_DLL | ( | bool | close_handle_on_destruction = true |
) | [explicit] |
Default constructor. By default, the close() operation on the object will be invoked before it is destroyed.
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.
: open_mode_ (0), dll_name_ (0), close_handle_on_destruction_ (close_handle_on_destruction), dll_handle_ (0), error_ (0) { ACE_TRACE ("ACE_DLL::ACE_DLL (int)"); }
ACE_DLL::ACE_DLL | ( | const ACE_TCHAR * | dll_name, | |
int | open_mode = ACE_DEFAULT_SHLIB_MODE , |
|||
bool | close_handle_on_destruction = true | |||
) | [explicit] |
This constructor performs the actions of open() during construction.
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:
| |
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.
: open_mode_ (open_mode), dll_name_ (0), close_handle_on_destruction_ (close_handle_on_destruction), dll_handle_ (0), error_ (0) { ACE_TRACE ("ACE_DLL::ACE_DLL"); if (this->open (dll_name, this->open_mode_, close_handle_on_destruction) != 0 && ACE::debug ()) ACE_ERROR ((LM_ERROR, ACE_TEXT ("ACE_DLL::open: error calling open: %s\n"), this->error ())); }
ACE_DLL::ACE_DLL | ( | const ACE_DLL & | rhs | ) |
Copy constructor.
Definition at line 31 of file DLL.cpp.
: open_mode_ (0), dll_name_ (0), close_handle_on_destruction_ (false), dll_handle_ (0), error_ (0) { ACE_TRACE ("ACE_DLL::ACE_DLL (const ACE_DLL &)"); if (rhs.dll_name_ // This will automatically up the refcount. && this->open (rhs.dll_name_, rhs.open_mode_, rhs.close_handle_on_destruction_) != 0 && ACE::debug ()) ACE_ERROR ((LM_ERROR, ACE_TEXT ("ACE_DLL::copy_ctor: error: %s\n"), this->error ())); }
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.
{ ACE_TRACE ("ACE_DLL::~ACE_DLL"); this->close (); // Normally delete()d in ACE_DLL::close(). However, that may not // occur if full ACE_DLL initialization is interrupted due to errors // (e.g. attempting to open a DSO/DLL that does not exist). Make // sure this->dll_name_ is deallocated. delete [] this->dll_name_; }
int ACE_DLL::close | ( | void | ) |
Call to close the DLL object.
Definition at line 198 of file DLL.cpp.
{ ACE_TRACE ("ACE_DLL::close"); int retval = 0; if (this->dll_handle_ && this->close_handle_on_destruction_ && this->dll_name_ && (retval = ACE_DLL_Manager::instance ()->close_dll (this->dll_name_)) != 0) this->error_ = 1; // Even if close_dll() failed, go ahead and cleanup. this->dll_handle_ = 0; delete [] this->dll_name_; this->dll_name_ = 0; this->close_handle_on_destruction_ = false; return retval; }
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.
{ ACE_TRACE ("ACE_DLL::error"); if (this->error_) { return ACE_OS::dlerror (); } return 0; }
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_handle_on_destruction
is set.
Definition at line 238 of file DLL.cpp.
{ ACE_TRACE ("ACE_DLL::get_handle"); ACE_SHLIB_HANDLE handle = ACE_SHLIB_INVALID_HANDLE; if (this->dll_handle_) handle = this->dll_handle_->get_handle (become_owner); return handle; }
int ACE_DLL::open | ( | const ACE_TCHAR * | dll_name, | |
int | open_mode = ACE_DEFAULT_SHLIB_MODE , |
|||
bool | close_handle_on_destruction = true | |||
) |
This method opens and dynamically links a specified DLL.
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:
| |
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(). |
-1 | On failure | |
0 | On success. |
int ACE_DLL::open_i | ( | const ACE_TCHAR * | dll_name, | |
int | open_mode = ACE_DEFAULT_SHLIB_MODE , |
|||
bool | close_handle_on_destruction = true , |
|||
ACE_SHLIB_HANDLE | handle = 0 | |||
) | [private] |
Definition at line 131 of file DLL.cpp.
{ ACE_TRACE ("ACE_DLL::open_i"); this->error_ = 0; if (!dll_filename) { if (ACE::debug ()) ACE_ERROR ((LM_ERROR, ACE_TEXT ("ACE_DLL::open_i: dll_name is %s\n"), this->dll_name_ == 0 ? ACE_TEXT ("(null)") : this->dll_name_)); return -1; } if (this->dll_handle_) { // If we have a good handle and its the same name, just return. if (ACE_OS::strcmp (this->dll_name_, dll_filename) == 0) return 0; else this->close (); } if (!this->dll_name_) this->dll_name_ = ACE::strnew (dll_filename); this->open_mode_ = open_mode; this->close_handle_on_destruction_ = close_handle_on_destruction; this->dll_handle_ = ACE_DLL_Manager::instance()->open_dll (this->dll_name_, this->open_mode_, handle); if (!this->dll_handle_) this->error_ = 1; return this->error_ ? -1 : 0; }
Allow assignment.
Definition at line 54 of file DLL.cpp.
{ ACE_TRACE ("ACE_DLL::operator= (const ACE_DLL &)"); ACE_DLL tmp (rhs); std::swap (this->open_mode_, tmp.open_mode_); std::swap (this->dll_name_, tmp.dll_name_); std::swap (this->close_handle_on_destruction_, tmp.close_handle_on_destruction_); std::swap (this->dll_handle_, tmp.dll_handle_); std::swap (this->error_, tmp.error_); return *this; }
int ACE_DLL::set_handle | ( | ACE_SHLIB_HANDLE | handle, | |
bool | close_handle_on_destruction = true | |||
) |
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 254 of file DLL.cpp.
{ ACE_TRACE ("ACE_DLL::set_handle"); // Create a unique name. Note that this name is only quaranteed // to be unique for the life of this object. ACE_TCHAR temp[ACE_UNIQUE_NAME_LEN]; ACE_OS::unique_name (this, temp, ACE_UNIQUE_NAME_LEN); return this->open_i (temp, 1, close_handle_on_destruction, handle); }
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().
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. |
Definition at line 178 of file DLL.cpp.
{ ACE_TRACE ("ACE_DLL::symbol"); this->error_ = 0; void *sym = 0; if (this->dll_handle_) sym = this->dll_handle_->symbol (sym_name, ignore_errors); if (!sym) this->error_ = 1; return sym; }
bool ACE_DLL::error_ |