ACE_DLL_Handle Class Reference

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

#include <DLL_Manager.h>

List of all members.

Public Member Functions

 ACE_DLL_Handle (void)
 Default construtor.
 ~ACE_DLL_Handle (void)
 Destructor.
const ACE_TCHARdll_name () const
 Returns the name of the shared library (without prefixes or suffixes).
int open (const ACE_TCHAR *dll_name, int open_mode, ACE_SHLIB_HANDLE handle)
int close (int unload=0)
sig_atomic_t refcount (void) const
 Return the current refcount.
void * symbol (const ACE_TCHAR *symbol_name, int ignore_errors=0)
ACE_SHLIB_HANDLE get_handle (int become_owner=0)

Private Member Functions

auto_ptr< ACE_TStringerror (void)
void get_dll_names (const ACE_TCHAR *dll_name, ACE_Array< ACE_TString > &try_names)
 ACE_DLL_Handle (const ACE_DLL_Handle &)
void operator= (const ACE_DLL_Handle &)

Private Attributes

sig_atomic_t refcount_
ACE_TCHARdll_name_
 Name of the shared library.
ACE_SHLIB_HANDLE handle_
 Handle to the actual library loaded by the OS.

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.


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]


Member Function Documentation

const ACE_TCHAR * ACE_DLL_Handle::dll_name ( void   )  const

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

int ACE_DLL_Handle::open ( const ACE_TCHAR dll_name,
int  open_mode,
ACE_SHLIB_HANDLE  handle 
)

This method opens and dynamically links dll_name. The default mode is <RTLD_LAZY>, which loads identifier symbols but not the symbols for functions, which are loaded dynamically on-demand. Other supported modes include: <RTLD_NOW>, which performs all necessary relocations when dll_name is first loaded and <RTLD_GLOBAL>, which makes symbols available for relocation processing of any other DLLs. Returns -1 on failure and 0 on success.

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;

sig_atomic_t ACE_DLL_Handle::refcount ( void   )  const

Return the current refcount.

void * ACE_DLL_Handle::symbol ( const ACE_TCHAR symbol_name,
int  ignore_errors = 0 
)

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.

ACE_SHLIB_HANDLE ACE_DLL_Handle::get_handle ( int  become_owner = 0  ) 

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

auto_ptr< ACE_TString > ACE_DLL_Handle::error ( void   )  [private]

Returns a pointer to a string explaining why <symbol> or <open> failed. 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]

void ACE_DLL_Handle::operator= ( const ACE_DLL_Handle  )  [private]


Member Data Documentation

Name of the shared library.

Handle to the actual library loaded by the OS.

ACE_BEGIN_VERSIONED_NAMESPACE_DECL sig_atomic_t ACE_DLL_Handle::open_called_ = 0 [static, private]

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


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

Generated on Wed Apr 23 02:38:49 2008 for ACE by  doxygen 1.5.5