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.


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


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


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


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


[view class]
handle
public:
IModuleHandle handle() const

Returns the module handle of the dynamic link library.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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


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


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


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


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


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

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data