 |
LoadDLL |
Function (tigcc.a) |
Loads a DLL into memory and prepares it for use.
LoadDLL tries to load a DLL into memory and to prepare it for use. It traverses the
complete VAT to find a fitting version of the DLL (so it is not necessary for the DLL to be in
the same directory as the main program). The DLLName parameter is the standard ANSI C name of
the DLL file which is to be loaded. The ID parameter is a DLL identification number introduced for safety
reasons: any file which does not have the extension 'DLL', a valid embedded signature and
an embedded identification number which is equal to ID is ignored (the identification
number in the DLL itself is set using the DLL_ID entry in the DLL interface section). The parameters
Major and Minor are the expected major and minor version numbers of the DLL (the actual major
and minor version numbers in the DLL itself are set using the DLL_VERSION macro in the DLL
interface section). LoadDLL will refuse to load a DLL if the expected and actual version
numbers are not the same, or if the expected minor version number is greater than the actual minor
version number. As LoadDLL searches trough all folders for a matching DLL, it is completely
legal to have several DLLs with the same name (in different folders), but which differ in
their ID numbers or version numbers. LoadDLL will load the first DLL found (if any)
with a matching name, ID number and major version number, and whose minor version number
is greater or equal to the expected minor version number.
LoadDLL returns one of the following values:
DLL_OK |
The DLL was loaded and initialized successfully. |
DLL_NOTINGHOSTSPACE |
The DLL could not be loaded because the program counter is not in the "ghost space" (the
virtual address space where HW2 protections do not take effect). Note that exe-packed
programs are always executed in the ghost space; if you do not want to compress your program,
you need to define
EXECUTE_IN_GHOST_SPACE . |
DLL_NOTFOUND |
The DLL is not found. This means that either a file with the name DLLName is not
found in any folder, or such files exist, but none of them has the correct extension ('DLL'), the correct
embedded signature, and the correct identification number (determined by the ID parameter). |
DLL_LOCKFAILED |
The attempt to lock the DLL in memory has failed due to some strange reason. This error code
is very unlikely. |
DLL_OUTOFMEM |
There is not memory to load the DLL into RAM. |
DLL_ALREADYLOADED |
There is already another DLL loaded in the RAM. Due to efficiency reasons, only one
DLL is allowed to be loaded at the same time. You need to unload the current DLL using
UnloadDLL before loading another one. Anyway, using more than
one DLL is strongly deprecated if you don't know exactly what you are doing and why you are
doing so. |
DLL_WRONGVERSION |
There is at least one valid DLL file with the name DLLName and with the correct extension,
signature, and identification number, but none of them has a major version number which is
equal to the expected major number (determined by the Major parameter) and a minor version number
which is greater or equal than the expected minor number (determined by the Minor parameter). |
Only if LoadDLL returns DLL_OK, it is valid to proceed further and to use functions imported
from the DLL. No further checking is done by the functions from the DLL, so your program will
definitely crash if you try to call any function from the DLL if LoadDLL has not returned DLL_OK.
Also, don't forget to call UnloadDLL when the DLL is not needed any more (usually at the end of
the program). So, any program which uses DLLs must have the following code fragment:
if ((status = LoadDLL (DLLName, ID, Major, Minor)) != DLL_OK)
{
// Perform some kind of error processing
// and terminate the program in some way
}
// Proceed further
UnloadDLL ();
You may use LoadDLLThrow instead, which
throws an error instead of returning an error code, but this means that you
can not determine what caused the problem. As another solution, you may use
ER_throw from
error.h to throw your own error if loading the
DLL fails.
Typically, if you use functions which may throw errors, you can either catch
these errors using
TRY...ONERR...ENDTRY
blocks, or, if you want to pass them on to the AMS, you
can use a single TRY...FINALLY...ENDFINAL block:
if ((status = LoadDLL (DLLName, ID, Major, Minor)) != DLL_OK)
{
// Perform some kind of error processing
// and terminate the program in some way
}
TRY
// Proceed further
FINALLY
UnloadDLL ();
ENDFINAL
Or, using LoadDLLThrow:
LoadDLLThrow (DLLName, ID, Major, Minor);
TRY
// Proceed further
FINALLY
UnloadDLL ();
ENDFINAL
Uses: HeapAllocPtr, HeapDeref, HeapGetLock, HeapLock, HeapUnlock, memcmp, strcmp, EX_patch, SymFindFirst, SymFindNext
Used by: LoadDLLThrow
See also: UnloadDLL, LoadDLLThrow, _DLL_call, _DLL_call_attr, _DLL_reference, _DLL_glbvar