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.


[view 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


[view class]
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


[view class]
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.


[view 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


[view class]
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.


[view class]
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


[view class]
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


[view class]
isOpen
public:
virtual bool isOpen() const

Returns true if the dynamic link library is open.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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.


[view class]
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


[view class]
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.


[view class]
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


[view class]
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


[view class]
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

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data