LoadLibraryEx
The LoadLibraryEx
function maps a specified executable module into the address space of the
calling process. The executable module can be a .DLL or an .EXE file. The
specified module may cause other modules to be mapped into the address space.
HINSTANCE LoadLibraryEx(
|
LPCTSTR lpLibFileName, |
// points to name
of executable module |
|
HANDLE hFile, |
// reserved, must
be NULL |
|
DWORD dwFlags |
// entry-point
execution flag |
|
); |
|
Parameters
lpLibFileName
Points to a
null-terminated string that names a Win32 executable module (either a .DLL or
an .EXE file). The name specified is the filename of the executable module.
This name is not related to the name stored in a library module itself, as
specified by the LIBRARY keyword in the module-definition (.DEF) file.
If the string specifies a path, but the file does not exist in the
specified directory, the function fails.
If the string does not specify a path, and the filename extension is
omitted, the function appends the default library extension .DLL to the filename.
However, the filename string can include a trailing point character (.) to
indicate that the module name has no extension.
If the string does not specify a path, the function uses a standard
search strategy to find the file. See the Remarks for more information.
If mapping the specified module into the address space causes the
operating system to map in other, associated executable modules, the function
can use either the standard search strategy or an alternate search strategy to
find those modules. See the Remarks for more information.
Once the function obtains a fully qualified path to a library module
file, the path is compared (in a case-independent manner) to the full paths of
library modules that are currently loaded into the calling process. That set of
libraries includes those that were loaded when the process was starting up, as
well as those previously loaded by calls to LoadLibrary or LoadLibraryEx
but not yet unloaded by calls to FreeLibrary. If the path matches the
path of an already loaded module, the function just increments the reference
count for the module, and returns the module handle for that library.
hFile
This
parameter is reserved for future use. It must be NULL.
dwFlags
Specifies the
action to take when loading the module. This parameter can be one of the
following values:
|
Flag |
Meaning |
|
DONT_RESOLVE_DLL_REFERENCES |
|
|
|
Windows
NT only: If this
value is given, and the executable module is a dynamic-link library (DLL),
the operating system does not call the DllEntryPoint function for process and
thread initialization and termination. Also, the system does not load
additional executable modules that are referenced by the specified module. If this
value is not given, and the executable module is a DLL, the operating system
calls the DllEntryPoint function for process and thread initialization
and termination. The system loads additional executable modules that are
referenced by the specified module. The behavior of the function is then
identical to that of LoadLibrary in this regard. |
|
LOAD_LIBRARY_AS_DATAFILE |
|
|
|
If this
value is given, the function does a simple mapping of the file into the
address space. Nothing is done relative to executing or preparing to execute
the code in the mapped file. The function loads the module as if it were a
data file. You can use the module handle that the function returns in this
case with the Win32 functions that operate on resources. Use this flag when
you want to load a DLL in order to extract messages or resources from it, and
have no intention of executing its code. If this value
is not given, the function maps the file into the address space in the manner
that is normal for an executable module. The behavior of the function is then
identical to that of LoadLibrary in this regard. |
|
LOAD_WITH_ALTERED_SEARCH_PATH |
|
|
|
If this
value is given, and lpLibFileName specifies a path, the function uses
the alternate file search strategy discussed in the Remarks section
following to find associated executable modules that the specified module
causes to be loaded. If this
value is not given, or if lpLibFileName does not specify a path, the
function uses the standard search strategy discussed in the Remarks
section following to find associated executable modules that the specified
module causes to be loaded. The behavior of the function is then identical to
that of LoadLibrary in this regard. |
Return Values
If the
function succeeds, the return value is a handle to the mapped executable
module.
If the
function fails, the return value is NULL. To get extended error information,
call GetLastError.
Remarks
Note that the
DONT_RESOLVE_DLL_REFERENCES flag is only implemented on the Windows NT
platform. It is not implemented on the Windows 95 platform.
The calling
process can use the handle returned by this function to identify the module in
calls to the GetProcAddress,
FindResource,
and LoadResource
functions.
The
LoadLibraryEx function is very similar to the LoadLibrary function. The differences
consist of a set of optional behaviors that LoadLibraryEx provides.
First, LoadLibraryEx can map a DLL module without calling the DllEntryPoint function of the DLL.
Second, LoadLibraryEx can use either of two file search strategies to
find executable modules that are associated with the specified module. Third, LoadLibraryEx
can load a module in a way that is optimized for the case where the module
will never be executed, loading the module as if it were a data file. You
select these optional behaviors by setting the dwFlags parameter; if dwFlags
is zero, LoadLibraryEx behaves identically to LoadLibrary.
If no path is
specified, the LoadLibraryEx function uses the same standard file search
strategy that LoadLibrary,
SearchPath,
and OpenFile
use to find the executable module and any associated executable modules that it
causes to be loaded. This standard strategy searches for a file in the
following sequence:
1. The directory from which the application loaded.
2. The current directory.
3. Windows 95: The Windows system directory. Use the GetSystemDirectory function to get the path
of this directory.
Windows NT:
The 32-bit Windows system directory. Use the GetSystemDirectory function
to get the path of this directory. The name of this directory is SYSTEM32.
4. Windows NT: The 16-bit Windows system directory. There is no
Win32 function that obtains the path of this directory, but it is searched. The
name of this directory is SYSTEM.
5. The Windows directory. Use the GetWindowsDirectory function to get the path
of this directory.
6. The directories that are listed in the PATH environment variable.
If a path is
specified, and the dwFlags parameter is set to
LOAD_WITH_ALTERED_SEARCH_PATH, the LoadLibraryEx function uses an
alternate file search strategy to find any executable modules that the
specified module causes to be loaded. This alternate strategy searches for a
file in the following sequence:
1. The directory specified by the lpLibFileName path. In other
words, the directory that the specified executable module is in.
2. The current directory.
3. Windows 95: The Windows system directory. Use the GetSystemDirectory function to get the path
of this directory.
Windows NT:
The 32-bit Windows system directory. Use the GetSystemDirectory function
to get the path of this directory. The name of this directory is SYSTEM32.
4. Windows NT: The 16-bit Windows system directory. There is no
Win32 function that obtains the path of this directory, but it is searched. The
name of this directory is SYSTEM.
5. The Windows directory. Use the GetWindowsDirectory function to get the path
of this directory.
6. The directories that are listed in the PATH environment variable.
Note that the
standard file search strategy and the alternate search strategy differ in just
one way: the standard strategy starts its search in the calling application s
directory, and the alternate strategy starts its search in the directory of the
executable module that LoadLibraryEx is loading.
If you
specify the alternate search strategy, its behavior continues until all
associated executable modules have been located. Once the system starts
processing DLL initialization routines, the system reverts to the standard
search strategy.
See Also