## NAME

ACE_DLL - Provides an abstract interface for handling various DLL operations.

## SYNOPSIS

    #include <ace/DLL.h>

    class ACE_DLL
    {
      public:
        ACE_DLL (int close_on_destruction = 1);
        ACE_DLL (
            const char *dll_name,
            int open_mode = ACE_DEFAULT_SHLIB_MODE,
            int close_on_destruction = 1
            );
        int open (
            const char *dll_name,
            int open_mode = ACE_DEFAULT_SHLIB_MODE,
            int close_on_destruction = 1
            );
        int close (void);
        ~ACE_DLL (void);
        void *symbol (const char *symbol_name);
        ASYS_TCHAR *error (void);
        ACE_SHLIB_HANDLE get_handle (int become_owner = 0);
        int set_handle (
            ACE_SHLIB_HANDLE handle,
            int close_on_destruction = 1
            );
      private:
        ACE_SHLIB_HANDLE handle_;
        int close_on_destruction_;
        inline ACE_UNIMPLEMENTED_FUNC (ACE_DLL (const ACE_DLL &));
    };

## DESCRIPTION

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. Operations `open`, `close`, and `symbol` have been implemented to help opening/closing and extracting symbol information from a DLL, respectively.

## Initialization and termination methods.

    ACE_DLL (int close_on_destruction = 1);

Default constructor. By default, the `close` operation on the object will be invoked before it is destroyed.

    ACE_DLL (
        const char *dll_name,
        int open_mode = ACE_DEFAULT_SHLIB_MODE,
        int close_on_destruction = 1
        );

This constructor 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.

    int open (
        const char *dll_name,
        int open_mode = ACE_DEFAULT_SHLIB_MODE,
        int close_on_destruction = 1
        );

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 close (void);

Call to close the DLL object.

    ~ACE_DLL (void);

Called when the DLL object is destroyed -- invokes `close` if the `close_on_destruction` flag is set in the constructor or `open` method.

    void *symbol (const char *symbol_name);

If `symbol_name` is in the symbol table of the DLL a pointer to the `symbol_name` is returned. Otherwise, returns 0.

    ASYS_TCHAR *error (void);

Returns a pointer to a string explaining why `symbol` or `open` failed.

    ACE_SHLIB_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 and the `ACE_DLL` object won't call `close` when it goes out of scope, even if `close_on_destruction` is set.

    int set_handle (
        ACE_SHLIB_HANDLE handle,
        int close_on_destruction = 1
        );

Set the handle for the DLL object. By default, the `close` operation on the object will be invoked before it is destroyed.

## Disallow copying and assignment since we don't handle these.

    inline ACE_UNIMPLEMENTED_FUNC (ACE_DLL (const ACE_DLL &));

## AUTHOR

Kirthika Parameswaran `kirthika@cs.wustl.edu`

## LIBRARY

ace