### IDLLModule

  The IDLLModule supports the loading, unloading, and addressing of entry points in a dynamic link library (DLL). Dynamic link libraryies are known as shared libraries on some platforms. IDLLModule makes it easier and safer to track loaded DLLs. It provides access to module information for those loaded DLLs, such as entry point addresses and the file name of the module.

### IDLLModule - Member Functions and Data by Group

### Constructors & Destructor

You can construct, destruct, copy, and assign objects of this class.

~IDLLModule

      public:
      ~IDLLModule()

  The dynamic link library is unloaded from memory if it is no longer being referenced.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

IDLLModule
  Constructs an IDLLModule object.

  Overload 1

      public:
      IDLLModule( const char* fileName,
                  ESearchLocation searchOrder = kOSDefaultSearch )

  fileName
    The dynamic link library name.
  searchLocation
    Search mechanism to use when the dynamic link library is not path qualified. No searching is performed on path qualified names.

  Use this version of the constructor if you know the name of the dynamic link library (DLL or shared library). This constructor opens the dynamic link library.
  Note: If you want to search the library path (LIBPATH or PATH) for the dynamic link library, specify fileName without the path or extension.

Exception

  IAccessError | The dynamic link library object was not created. The system either could not locate the file, or (for OS/2) the LIBRARY statement in the .def file does not match the DLL name.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      IDLLModule(const IModuleHandle& moduleHandle)

  moduleHandle
    Reference to a module handle of a dynamic link library that has been loaded explicitly.

  Use this version of the constructor if you have an IModuleHandle obtained by previously loading the dynamic link library (DLL).

Exception

  IAccessError | The dynamic link library object was not created. The module handle may be invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

  Overload 3

      public:
      IDLLModule(const IDLLModule& dllLibrary)

  dllLibrary
    Reference to an existing IDLLModule object.

  Creates a dynamic link library object using a reference to an existing dynamic link library object. This is commonly known as a copy constructor.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

operator =

      public:
      IDLLModule& operator =(const IDLLModule& dllLibrary)

  Assigns the member data of an object of this class to another object of this class.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Dynamic Link Library Information

Use these members to query information about the loaded dynamic link library.

fileName

      public:
      IString fileName() const

  Returns the fully qualified file name of the dynamic link library.

Exception

  IAccessError | The file name was not returned. The module handle may be invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

handle

      public:
      IModuleHandle handle() const

  Returns the module handle of the dynamic link library.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

isOpen

      public:
      bool isOpen() const

  Returns true if the dynamic link library is open.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Opening and Closing

Use these members to open (load) and close (unload) a dynamic link library.

close

      public:
      IDLLModule& close()

  Decrements the reference count of the dynamic link library. If the count reaches 0, this call also closes the library.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

open

      public:
      IDLLModule& open()

  Opens a closed dynamic link library and increments the reference count.

Exception

  IAccessError | The dynamic link library object was not created. The system either could not locate the file, or (for OS/2) the LIBRARY statement in the .def file does not match the DLL name.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Procedure Address Loading

Use these members to call a function in a dynamic link library. You can identify a function by its name or ordinal number.

isEntryPoint32Bit
  Returns true if the entry point is 32-bit.

  Overload 1

      public:
      bool isEntryPoint32Bit(const char* procedureName) const

  procedureName
    Pointer to the procedure name.

  Use this version of the function if you know the entry point's name.

Exception

  IAccessError | The entry point was not queried. The procedure name may be invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

  Overload 2

      public:
      bool
        isEntryPoint32Bit( unsigned long procedureOrdinal ) const

  procedureOrdinal
    Unsigned long value that represents the procedure ordinal.

  Use this version of the function if you know the entry point's ordinal.

Exception

  IAccessError | The entry point was not queried. The procedure ordinal may be invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

procAddress
  Returns the address of the procedure.

  Overload 1

      public:
      void* procAddress(const char* procedureName) const

  procedureName
    Pointer to the procedure name.

  Use this version of the function if you know the procedure name.

Exception

  IAccessError | The procedure address was not loaded. The procedure name may be invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      void* procAddress(unsigned long procedureOrdinal) const

  procedureOrdinal
    Unsigned long value that represents the procedure ordinal.

  Use this version of the function if you know the procedure ordinal.

Exception

  IAccessError | The procedure address was not loaded. The procedure ordinal may be invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

### IDLLModule - Enumerations

ESearchLocation

      enum ESearchLocation { kOSDefaultSearch,
                             kNLSPathSearch }

  Use these enumerators to specify how to search for a dynamic link library (DLL or shared library). Valid values are:

  kOSDefaultSearch
    Finds a dynamic link library using the PATH or LIBPATH environment variables following the search rules of the native operating system.
  kNLSPathSearch
    Finds the dynamic link library using the NLSPATH environment variable after substituting %L with the user's current locale. (On Windows and OS/2, it is the LANG environment variable.)

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

AIX Considerations
  Instead of using the LANG environment, the current user's locale is retrieved from a call to setlocale(LC_MESSAGES, NULL).

### IDLLModule - Inherited Member Functions and Data

#### Inherited Public Functions

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None