Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function maps the specified DLL file into the address space of the calling process.

Syntax

HINSTANCE LoadLibrary(
  LPCTSTR 
lpLibFileName
);

Parameters

lpLibFileName

[in] Pointer to a null-terminated string that names the DLL file.

The name specified is the file name of the module and is not related to the name stored in the library module itself, as specified by the LIBRARYkeyword 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, the function uses a standard search strategy to find the file. For more information, see the Remarks section.

Return Value

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

Remarks

LoadLibrarycan be used to doing the following:

  • Map a DLL module and return a handle that can be used in GetProcAddressto get the address of a DLL function. You need to use FreeLibraryon the handle later.

  • Map other executable modules. For example, the function can specify an .exe file to get a handle that can be used in FindResourceor LoadResource.

Do not use LoadLibraryto run a .exe file. Use the CreateProcessfunction.

Applications should cache the handle returned by LoadLibraryto 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.

If the module is a DLL not already mapped for the calling process, the system calls the DLL's DllMainfunction with the DLL_PROCESS_ATTACH value.

In Windows Mobile, a DLL is loaded once, but is then mapped into each process's address space when a process implicitly or explicitly loads the library with the LoadLibraryfunction.

When Windows Mobile loads a DLL, all path information is ignored when determining if the DLL is already loaded. This means that if a DLL with the same name is currently loaded by any process on the system the search order is ignored, even if the path is absolute. In addition, a module ending with the extension .cpl is treated as if the extension is .dll. For example, if Process A loads \Private\mydll.dll and Process B calls LoadLibrary("\Windows\mydll.dll"), Process B will get \Private\mydll.dll.

It is not safe to call LoadLibraryfrom DllMain.

Module handles are not global or inheritable. A call to LoadLibraryby one process does not produce a handle that another process can use — for example, in calling GetProcAddress. The other process must make its own call to LoadLibraryfor the module before calling GetProcAddress.

Two different modules cannot have the same file name, even if the extensions are different. These effectively have the same module name. For example, if LoadLibraryis made on Sample.cpl, the OS does not load Sample.cpl, but instead loads Sample.dll again.

A similar limitation exists for modules with the same name but residing in different directories. For example, if LoadLibraryis called on \\Windows\Sample.dll, and then LoadLibraryis called on \\MyDir\Sample.dll, \\Windows\Sample.dll will simply be reloaded.

If no file name extension is specified in the lpLibFileNameparameter, the default library extension .dll is appended. However, the file name string can include a trailing point character (.) to indicate that the module name has no extension.

A search path to the executable module cannot be specified.

Unless the full path to the module is specified, Windows Mobile searches the following path for the module:

  • The absolute path specified by the lpLibFileNameparameter.

  • The .exe launch directory.

  • The Windows directory.

  • ROM DLL files.

  • An OEM-specified search path.

The following registry subkey specifies a search path to use with LoadLibraryand CreateProcess:

Copy Code
HKEY_LOCAL_MACHINE\Loader
   SystemPath=multi_sz:\\path1\\
					 \\path2\\

The path is only searched if the path of the file being looked for is not explicitly specified.

The total length of the SystemPathvalue must not exceed 260 characters. If it does, the path is ignored.

A change to the SystemPathkey does not take effect until a Windows ®phone is reset.

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.

Process (.exe) run mode Trusted DLL run mode Untrusted DLL run mode

Trusted

DLL loads as trusted.

DLL not loaded.

Untrusted

DLL loads as untrusted.

DLL loaded as untrusted.

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

Requirements

Header winbase.h
Library coredll.lib
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also