ACE  6.1.0
Public Member Functions | Public Attributes | Private Member Functions
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 (bool close_handle_on_destruction=true)
ACE_DLLoperator= (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_TCHARerror (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_TCHARdll_name_
bool close_handle_on_destruction_
ACE_DLL_Handledll_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)

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.


Constructor & Destructor Documentation

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.

Parameters:
close_handle_on_destructionIndicates 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().
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.

Parameters:
dll_nameThe name or path of the DLL to load.
open_modeFlags 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_destructionIndicates 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().
ACE_DLL::ACE_DLL ( const ACE_DLL rhs)

Copy constructor.

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.


Member Function Documentation

int ACE_DLL::close ( void  )

Call to close the DLL object.

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.

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.

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.

Parameters:
dll_nameThe filename or path of the DLL to load. ACE will attempt to apply the platform's standard library/DLL prefixes and suffixes, allowing a simple, unadorned name to be passed regardless of platform. The set of name transforms is listed below. A decorator is a platform's name designator for a debug vs release build. For example, on Windows it is usually "d".
  • Name + decorator + suffix
  • Name + suffix
  • Prefix + name + decorator + suffix
  • Prefix + name + suffix
  • Name Note that the transforms with decorator will be avoided if ACE is built with the ACE_DISABLE_DEBUG_DLL_CHECK config macro.
There is another mode for locating library/DLL files that was used in old versions of ACE. The alternate method builds more combinations of pathname by combining the names transforms above with locations listed in the platform's standard "path" locations (e.g., LD_LIBRARY_PATH). It can be enabled by building ACE with the ACE_MUST_HELP_DLOPEN_SEARCH_PATH config macro. Use of this option is discouraged since it avoids the standard platform search options and security mechanisms.
open_modeFlags 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_destructionIndicates 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:
-1On failure
0On 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]
ACE_DLL & ACE_DLL::operator= ( const ACE_DLL rhs)

Allow assignment.

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.

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_nameThe symbol name to look up.
ignore_errorsIf 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.

Member Data Documentation

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

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.

Flag to record if the last operation had an error.

Open mode.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines