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

#include <DLL_Manager.h>

Public Types
typedef ACE_Fixed_Stack< ACE_TString, 10 >	ERROR_STACK
	Error stack. Fixed size should suffice. Ignores any errors exceeding the size. More...

Public Member Functions
	ACE_DLL_Handle (void)
	Default construtor. More...

	~ACE_DLL_Handle (void)
	Destructor. More...

const ACE_TCHAR *	dll_name () const
	Returns the name of the shared library (without prefixes or suffixes). More...

int	open (const ACE_TCHAR dll_name, int open_mode, ACE_SHLIB_HANDLE handle, ERROR_STACK errors=0)

int	close (int unload=0)

sig_atomic_t	refcount (void) const
	Return the current refcount. More...

void *	symbol (const ACE_TCHAR *symbol_name, bool ignore_errors=false)

void *	symbol (const ACE_TCHAR *symbol_name, bool ignore_errors, ACE_TString &error)
	Resolves and returns any error encountered. More...

ACE_SHLIB_HANDLE	get_handle (bool become_owner=false)

Public Attributes
	ACE_ALLOC_HOOK_DECLARE

Private Member Functions
ACE_TString &	error (ACE_TString &err)

void	get_dll_names (const ACE_TCHAR *dll_name, ACE_Array< ACE_TString > &try_names)

	ACE_DLL_Handle (const ACE_DLL_Handle &)
	Disallow copying and assignment since we don't handle them. More...

void	operator= (const ACE_DLL_Handle &)

Private Attributes
sig_atomic_t	refcount_

ACE_TCHAR *	dll_name_
	Name of the shared library. More...

ACE_SHLIB_HANDLE	handle_
	Handle to the actual library loaded by the OS. More...

Static Private Attributes
static sig_atomic_t	open_called_ = 0

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. It is refcounted and managed by ACE_DLL_Manager, so there will only be a single instance of this class for each dll loaded, no matter how many instances of ACE_DLL an application has open. Operations open(), close(), and symbol() have been implemented to help opening/closing and extracting symbol information from a DLL, respectively.

Most of this class came from the original ACE_DLL class. ACE_DLL is now just an interface that passed all it's calls either directly or via ACE_DLL_Manager to this class for execution.

Member Typedef Documentation

typedef ACE_Fixed_Stack< ACE_TString, 10 > ACE_DLL_Handle::ERROR_STACK

Error stack. Fixed size should suffice. Ignores any errors exceeding the size.

Constructor & Destructor Documentation

ACE_DLL_Handle::ACE_DLL_Handle ( void )

Default construtor.

ACE_DLL_Handle::~ACE_DLL_Handle ( void )

Destructor.

ACE_DLL_Handle::ACE_DLL_Handle ( const ACE_DLL_Handle & )

private

Disallow copying and assignment since we don't handle them.

Member Function Documentation

int ACE_DLL_Handle::close ( int unload = 0 )

Call to close the DLL object. If unload = 0, it only decrements the refcount, but if unload = 1, then it will actually unload the library when the refcount == 0;

const ACE_TCHAR * ACE_DLL_Handle::dll_name ( void ) const

Returns the name of the shared library (without prefixes or suffixes).

ACE_TString & ACE_DLL_Handle::error ( ACE_TString & err )

private

Returns a string explaining why <symbol> or <open> failed in err. This is used internal to print out the error to the log, but since this object is shared, we can't store or return the error to the caller.

void ACE_DLL_Handle::get_dll_names	(	const ACE_TCHAR *	dll_name,
		ACE_Array< ACE_TString > &	try_names
	)

private

Builds array of DLL names to try to dlopen, based on platform and configured DLL prefixes/suffixes. Returns the array of names to try in try_names.

ACE_SHLIB_HANDLE ACE_DLL_Handle::get_handle ( bool become_owner = false )

Return the handle to the caller. If become_owner is true then caller assumes ownership of the handle so we decrement the retcount.

int ACE_DLL_Handle::open	(	const ACE_TCHAR *	dll_name,
		int	open_mode,
		ACE_SHLIB_HANDLE	handle,
		ERROR_STACK *	errors = `0`
	)

This method opens and dynamically links a library/DLL.

Parameters

dll_name	The 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". Prefix + name + decorator + suffix Prefix + name + suffix Name + decorator + suffix 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_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.
handle	If a value other than `ACE_INVALID_HANDLE` is supplied, this object is assigned the specified handle instead of attempting to open the specified dll_name.
errors	Optional address of an error stack to collect any errors encountered.

Return values

-1	On failure
0	On success.

void ACE_DLL_Handle::operator= ( const ACE_DLL_Handle & )

private

sig_atomic_t ACE_DLL_Handle::refcount ( void ) const

Return the current refcount.

void * ACE_DLL_Handle::symbol	(	const ACE_TCHAR *	symbol_name,
		bool	ignore_errors = `false`
	)

If symbol_name is in the symbol table of the DLL a pointer to the symbol_name is returned. Otherwise, returns 0. Set the ignore_errors flag to supress logging errors if symbol_name isn't found. This is nice if you just want to probe a dll to see what's available, since missing functions in that case aren't really errors.

void * ACE_DLL_Handle::symbol	(	const ACE_TCHAR *	symbol_name,
		bool	ignore_errors,
		ACE_TString &	error
	)

Resolves and returns any error encountered.

Member Data Documentation

ACE_DLL_Handle::ACE_ALLOC_HOOK_DECLARE

ACE_TCHAR* ACE_DLL_Handle::dll_name_

private

Name of the shared library.

ACE_SHLIB_HANDLE ACE_DLL_Handle::handle_

private

Handle to the actual library loaded by the OS.

sig_atomic_t ACE_DLL_Handle::open_called_ = 0

staticprivate

Keeps track of whether or not open() has ever been called. This helps get around problem on Linux, and perhaps other OS's, that seg-fault if dlerror() is called before the ld library has been initialized by a call to dlopen().

sig_atomic_t ACE_DLL_Handle::refcount_

private

Keep track of how many ACE_DLL objects have a reference to this dll.

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

Public Types

Public Member Functions

Public Attributes

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation