| Platform SDK: DLLs, Processes, and Threads |
The LoadLibraryEx function maps the 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.
HMODULE LoadLibraryEx( LPCTSTR lpFileName, // file name of module HANDLE hFile, // reserved, must be NULL DWORD dwFlags // entry-point execution option );
If the string specifies a path, but the file does not exist in the specified directory, the function fails. When specifying a path, be sure to use backslashes (\), not forward slashes (/).
If the string does not specify a path, and the file name extension is omitted, the function appends the default library extension .dll to the file name. However, the file name 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 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.
| Flag | Meaning |
|---|---|
| DONT_RESOLVE_DLL_REFERENCES | Windows NT/ 2000: If this value is used, and the executable module is a DLL, the system does not call DllMain 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 used, and the executable module is a DLL, the system calls DllMain for process and thread initialization and termination. The system loads additional executable modules that are referenced by the specified module. |
| LOAD_LIBRARY_AS_DATAFILE | If this value is used, the system maps the file into the calling process's virtual address space as if it were a data file. Nothing is done to execute or prepare to execute the mapped file. Use this flag when you want to load a DLL only to extract messages or resources from it.
Windows NT/ 2000: You can use the resulting module handle with any Win32 functions that operate on resources. Windows 95/98: You can use the resulting module handle only with resource management functions such as EnumResourceLanguages, EnumResourceNames, EnumResourceTypes, FindResource, FindResourceEx, LoadResource, and SizeofResource. You cannot use this handle with specialized resource management functions such as LoadBitmap, LoadCursor, LoadIcon, LoadImage, and LoadMenu. |
| LOAD_WITH_ALTERED_SEARCH_PATH | If this value is used, and lpFileName specifies a path, the system uses the alternate file search strategy discussed in the Remarks section to find associated executable modules that the specified module causes to be loaded.
If this value is not used, or if lpFileName does not specify a path, the system uses the standard search strategy discussed in the Remarks section to find associated executable modules that the specified module causes to be loaded. |
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.
Windows 95: If you are using LoadLibraryEx to load a module that contains a resource whose numeric identifier is greater than 0x7FFF, LoadLibraryEx fails. If you are attempting to load a 16-bit DLL directly from 32-bit code, LoadLibraryEx fails. If you are attempting to load a DLL whose subsystem version is greater than 4.0, LoadLibraryEx fails. If your DllMain function tries to call the Unicode version of a Win32 function, LoadLibraryEx fails.
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 DllMain 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.
It is not safe to call LoadLibraryEx from DllMain. For more information, see the Remarks section in DllMain.
If no path is specified in the lpFileName parameter, and the base file name does not match the base file name of a loaded module, 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:
Windows NT/ 2000: The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.
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:
Windows NT/ 2000: The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.
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. After the system starts processing DLL initialization routines, the system reverts to the standard search strategy.
Windows 2000: If a path is specified and there is a redirection file associated with the application, the LoadLibraryEx function searches for the module in the application directory. If the module exists in the application directory, LoadLibraryEx ignores the path specification and loads the module from the application directory. If the module does not exist in the application directory, the function loads the module from the specified directory.
Visual C++: The Visual C++ compiler supports a syntax that enables you to declare thread-local variables: _declspec(thread). If you use this syntax in a DLL, you will not be able to load the DLL explicitly using LoadLibrary or LoadLibraryEx. If your DLL will be loaded explicitly, you must use the thread local storage functions instead of _declspec(thread).
Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98: Requires Windows 95 or later.
Header: Declared in Winbase.h; include Windows.h.
Library: Use Kernel32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.
Dynamic-Link Libraries Overview, Dynamic-Link Library Functions, DllMain, FindResource, FreeLibrary, GetProcAddress, GetSystemDirectory, GetWindowsDirectory, LoadLibrary, LoadResource, OpenFile, SearchPath