LoadLibraryEx

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This 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 can cause other modules to be mapped into the address space.

Syntax

HMODULE LoadLibraryEx(
  LPCTSTR lpLibFileName,
  HANDLE hFile,
  DWORD dwFlags
);

Parameters

• lpLibFileName
  [in] Pointer to a null-terminated string that names the executable module (either a .dll or an .exe file).

  The name specified is the file name 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.

  When specifying a path, 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 LoadLibrary function.

  If mapping the specified module into the address space causes the system to map in other associated executable modules, the function uses the standard search strategy specified by LoadLibrary.

• hFile
  [in] Reserved for future use. It must be set to NULL.

• dwFlags
  [in] Specifies the action to take when loading the module.

  If no flags are specified, the behavior of this function is identical to that of the LoadLibrary function.

  The following table shows possible values for this parameter.

  Flag	Description
  DONT_RESOLVE_DLL_REFERENCES	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 virtual address space of the calling process as if it were a data file. Nothing is done to execute or prepare to execute the mapped file. Use this flag to load a DLL only to extract messages or resources from it. You can use the resulting module handle with any Win32 functions that operate on resources. DONT_RESOLVE_DLL_REFERENCES is implied.
  LOAD_WITH_ALTERED_SEARCH_PATH	Not supported on Windows Embedded CE.

Return Value

A handle to the mapped executable module indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

The calling process can use the handle returned by this function to identify the module in calls to the GetProcAddress, FindResource, and LoadResource functions. You need to use FreeLibrary on the handle later.

Applications should cache the handle returned by LoadLibraryEx to reduce the need for multiple redudant calls. This is of particular performance value when working with the MUI DLL modules, as the libraries will need to be loaded across multiple resources.

The LoadLibraryEx function is 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 load a module in a way that is optimized for the case where the module is never 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 lpLibFileName 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 uses to find the executable module and associated executable modules that it causes to be loaded.

Because Windows Embedded CE only loads the same module once, the dwFlags settings are used for all further loads of the module.

• lpLibFileName
  If the module was already loaded using different parameters, the second attempt to load it fails.

When loading a DLL from a process, the run mode of the DLL depends on the run mode of the process. The following table shows the run mode of the DLL depending on whether the calling process is trusted or untrusted.

Loader can check the DLL header to determine whether the DLL contains code. DLLs must be trusted, and must pass the Loader before a trusted process can use them.

For information about the security model used on Windows Mobile devices, see Windows Mobile Device Security Model.

Requirements

See Also

Reference

DLL Functions
DllMain
FreeLibrary
GetProcAddress
LoadLibrary

Other Resources

FindResource
LoadResource
Loader