Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class 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:

[legend]
List of all members.

## Public Member Functions
| ACE_DLL (int close_handle_on_destruction=1)
| 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().
## 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)
void | operator= (const ACE_DLL &)
## Private 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.

## 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_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().

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().

ACE_DLL::ACE_DLL | ( | const ACE_DLL & |  | ) |

| 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`,
|  | int | close_handle_on_destruction = `1`
| ) |

  | This method opens and dynamically links a specified DLL. 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().
  Return values:
  | -1 | On failure
  | 0 | On success.

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]`

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

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().

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.

## Member Data Documentation

int ACE_DLL::close_handle_on_destruction_`[private]`

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

ACE_DLL_Handle* ACE_DLL::dll_handle_`[private]`

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.

int ACE_DLL::error_`[private]`

| Flag to record if the last operation had an error.

int ACE_DLL::open_mode_`[private]`

| Open mode.

The documentation for this class was generated from the following files:

- DLL.h
- DLL.cpp