Share via

LoadLibraryEx

  • Article

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

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, 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 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
    This parameter is reserved for future use. It must be 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. This parameter can be one of the following values.

    Flag Meaning
    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 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.

    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 Windows CE: not supported.

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

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 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 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 any associated executable modules that it causes to be loaded.

Because Windows CE will only load the same module exactly once, the dwFlags settings will be used for all further loads of the module. If the module was already loaded using different parameters then the second attempt to load it will fail.

Requirements

Runs On Versions Defined in Include Link to
Windows CE OS 3.0 and later Winbase.h   Nk.lib

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

DllMain, FindResource, FreeLibrary, GetLastError, GetProcAddress, LoadLibrary, LoadResource

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.