ACE_DLL Class Reference

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

#include <DLL.h>

Collaboration diagram for ACE_DLL:

[legend]List of all members.

Public Member Functions
	ACE_DLL (int close_handle_on_destruction=1)
const 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 19 of file DLL.cpp. References ACE_TRACE. : 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, 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 79 of file DLL.cpp. References ACE_ERROR, ACE_LIB_TEXT, ACE_TCHAR, ACE_TRACE, ACE::debug(), LM_ERROR, and open(). : 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_LIB_TEXT ("ACE_DLL::open: error calling open: %s\n"), this->error ())); }

ACE_DLL::ACE_DLL (  const ACE_DLL &   )

Copy constructor. Definition at line 29 of file DLL.cpp. References ACE_ERROR, ACE_LIB_TEXT, ACE_TRACE, close_handle_on_destruction_, ACE::debug(), dll_name_, LM_ERROR, open(), and open_mode_. : open_mode_ (0), dll_name_ (0), close_handle_on_destruction_ (0), 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_LIB_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 101 of file DLL.cpp. References ACE_TRACE, close(), and dll_name_. { 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_; }

---

Member Function Documentation

int ACE_DLL::close (  void   )

Call to close the DLL object. Definition at line 203 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 open_i(), and ~ACE_DLL(). { 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_ = 0; 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 227 of file DLL.cpp. References ACE_LIB_TEXT, ACE_TRACE, and error_. Referenced by ACE_Location_Node::open_dll(), ACE_Function_Node::symbol(), and ACE_Object_Node::symbol(). { ACE_TRACE ("ACE_DLL::error"); if (this->error_) return const_cast<ACE_TCHAR *> (ACE_LIB_TEXT ("Error: check log for details.")); 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 is set. Definition at line 242 of file DLL.cpp. References ACE_SHLIB_HANDLE, ACE_SHLIB_INVALID_HANDLE, ACE_TRACE, dll_handle_, and ACE_DLL_Handle::get_handle(). { 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, 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 126 of file DLL.cpp. References ACE_TCHAR, ACE_TRACE, and open_i(). Referenced by ACE_DLL(), ACE_Location_Node::open_dll(), and operator=(). { ACE_TRACE ("ACE_DLL::open"); return open_i (dll_filename, open_mode, close_handle_on_destruction); }

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 136 of file DLL.cpp. References ACE_ERROR, ACE_LIB_TEXT, ACE_SHLIB_HANDLE, ACE_TCHAR, 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(). { ACE_TRACE ("ACE_DLL::open_i"); this->error_ = 0; if (!dll_filename) { if (ACE::debug ()) ACE_ERROR ((LM_ERROR, ACE_LIB_TEXT ("ACE_DLL::open_i: dll_name is %s\n"), this->dll_name_ == 0 ? ACE_LIB_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; }

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

Allow assignment. Definition at line 52 of file DLL.cpp. References ACE_ERROR, ACE_LIB_TEXT, ACE_TRACE, close_handle_on_destruction_, ACE::debug(), dll_handle_, dll_name_, error_, LM_ERROR, open(), and open_mode_. { ACE_TRACE ("ACE_DLL::operator= (const ACE_DLL &)"); open_mode_ = 0; dll_name_ = 0; close_handle_on_destruction_=0; dll_handle_=0; error_=0; if (rhs.dll_name_ // This will automatically up the refcount and initialize *this && this->open (rhs.dll_name_, rhs.open_mode_, rhs.close_handle_on_destruction_) != 0 && ACE::debug ()) ACE_ERROR ((LM_ERROR, ACE_LIB_TEXT ("ACE_DLL::operator=: error: %s\n"), this->error ())); return *this; }

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 258 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(). { 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(). 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 183 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(). { 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; }

---

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=(), 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:

• DLL.h
• DLL.cpp

---