### IDynamicLinkLibrary

  The IDynamicLinkLibrary class supports the loading of resources from a dynamic link library (DLL).

### IDynamicLinkLibrary - Member Functions and Data by Group

### Constructors & Destructor

You can construct, copy, assign, and destruct objects of this class. You can construct objects of this class using either a dynamic link library name, module handle, or a reference to an existing object of this class.

~IDynamicLinkLibrary

      public:
      virtual ~IDynamicLinkLibrary()

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

Supported Platforms

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

IDynamicLinkLibrary

  Overload 1

      public:
      IDynamicLinkLibrary( const char* fileName,
                           ESearchLocation searchLocation = 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 used to build the DLL does not match the DLL name. You also may receive this error if you used the rename system command to rename the dynamic link library rather than the utility program DLLRNAME.

Supported Platforms

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

  Overload 2

      public:
      IDynamicLinkLibrary(const IDynamicLinkLibrary& dllLibrary)

  dllLibrary
    Reference to an existing IDynamicLinkLibrary 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

  Overload 3

      public:
      IDynamicLinkLibrary(const IModuleHandle& moduleHandle)

  moduleHandle
    Reference to a module handle of a DLL that has been loaded explicitly.

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

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

operator =

      public:
      IDynamicLinkLibrary&
        operator =( const IDynamicLinkLibrary& 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

### Diagnostics

Use these members for diagnostic purposes. They return an IString representation of an object of this class.

asDebugInfo

      public:
      virtual IString asDebugInfo() const

  Provides textual information about the class object. It returns a string that contains the file name of the dynamic link library.

Supported Platforms

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

asString

      public:
      virtual IString asString() const

  Provides textual information about the class object. It returns a string that contains the file name of the dynamic link library.

Supported Platforms

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

### Dynamic Link Library Information

Use these members to query general dynamic link library information.

fileName

      public:
      virtual 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. Check to ensure that the dynamic link library has been properly opened.

Supported Platforms

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

handle

      public:
      virtual IModuleHandle handle() const

  Returns the module handle of the dynamic link library. If the dynamic link library is not open, the module handle is 0.

Supported Platforms

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

isOpen

      public:
      virtual bool isOpen() const

  Returns true if the dynamic link library is open.

Supported Platforms

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

resourceAddress

      protected:
      virtual void* resourceAddress() const

  This is an internal use only function used to load resources on Motif.

Supported Platforms

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

### Opening and Closing

Use these members to open (load) or close (unload) a dynamic link library (DLL).
Note: DLL objects are reference-counted. When a DLL is opened, the reference count is incremented, and when it is closed, the reference count is decremented. When the reference count reaches 0, the DLL is unloaded from memory.

close

      public:
      virtual IDynamicLinkLibrary& close()

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

Supported Platforms

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

open

      public:
      virtual IDynamicLinkLibrary& open()

  Opens (loads) 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. You also may receive this error if you used the rename system command to rename the dynamic link library rather than the utility program DLLRNAME.

Supported Platforms

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

### Procedure Address Loading

Use these members to get a procedure address from a dynamic link library or to test the memory model of an entry point.

isEntryPoint32Bit

  If the entry point is a 32-bit function, true is returned.

  Overload 1

      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 or the dynamic link library may not be open.

Supported Platforms

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

  Overload 2

      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 or the dynamic link library may not be open.

Supported Platforms

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

procAddress

  Returns the address of the specified procedure address from a dynamic link library.

  Overload 1

      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 or the dynamic link library may not be open.

Supported Platforms

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

  Overload 2

      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 or the dynamic link library may not be open.

Supported Platforms

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

### IDynamicLinkLibrary - 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 users' 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 user's current locale is retrieved from a call to setlocal(LC_MESSAGES, NULL).

### IDynamicLinkLibrary - Inherited Member Functions and Data

#### Inherited Public Functions

  IResourceLibrary

  -     virtual ~IResourceLibrary()

  -     IResourceLibrary()

  -     IResourceLibrary(const IResourceLibrary& resLibrary)

  -     virtual IAccelTblHandle
          loadAccelTable( unsigned long accelTableId ) const

  -     virtual IBitmapHandle
          loadBitmap( unsigned long bitmapId,
                      bool cached = true ) const

  -     virtual IBitmapHandle
          loadBitmap( unsigned long bitmapId,
                      const ISize& bitmapSize,
                      bool cached = true ) const

  -     virtual IWindowHandle
          loadDialog( unsigned long dialogId,
                      IWindow* dialogParent,
                      IWindow* dialogOwner,
                      IWinProc* dialogProcedure,
                      void* dialogCreateParameters ) const

  -     virtual IResourceLibrary&
          loadHelpTable( IWindow* helpInstance,
                         unsigned long helpTableId ) const

  -     virtual IPointerHandle
          loadIcon( unsigned long iconId,
                    bool cached = true ) const

  -     virtual IMenuHandle
          loadMenu( unsigned long menuId,
                    IWindow* menuOwner ) const

  -     virtual void
          loadMenu( unsigned long menuId,
                    const IWindowHandle& menuHandle,
                    IMenu* parentMenu ) const

  -     virtual IString loadMessage(unsigned long messageId) const

  -     virtual IPointerHandle
          loadPointer( unsigned long iconId,
                       bool cached = true ) const

  -     virtual IString loadString(unsigned long stringId) const

  -     IResourceLibrary&
          operator =( const IResourceLibrary& resLibrary )

  -     virtual IBitmapHandle
          tryToLoadBitmap( unsigned long bitmapId,
                           bool cached = true ) const

  -     virtual IBitmapHandle
          tryToLoadBitmap( unsigned long bitmapId,
                           const ISize& bitmapSize,
                           bool cached = true ) const

  -     virtual IPointerHandle
          tryToLoadIcon( unsigned long iconId,
                         bool cached = true ) const

  -     virtual IString
          tryToLoadMessage( unsigned long messageId ) const

  -     virtual IPointerHandle
          tryToLoadPointer( unsigned long iconId,
                            bool cached = true ) const

  -     virtual IString
          tryToLoadString( unsigned long stringId ) const

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None