LoadLibrary (Windows CE 5.0)
This function maps the specified DLL file into the address space of the calling process.
HINSTANCELoadLibrary( LPCTSTRlpLibFileName);
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 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, the function uses a standard search strategy to find the file. For more information, see the Remarks.
Return Values
A handle to the module indicates success. NULL indicates failure. To get extended error information, call GetLastError.
Remarks
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. |
Resource only DLLs are DLLs that do not contain any code; they contain data such as strings, icons, and bitmaps. The Loader can check the resource only DLL's header to determine whether the resource only DLL contains code. Resource only DLLs must be trusted, and must pass the Loader before they can be used by a trusted process. To trust a resource only DLL, the Loader must sign and verify the resource only DLL, or the resource only DLL must be stored in ROM by adding the resource only DLL to the MODULES Section. All information stored in ROM is trusted, so resource only DLLs in the MODULES section do not need to be signed. Then, these unsigned resource only DLLs can be used by trusted processes. Romimage does not allocate any virtual memory for resource only DLLs because resource only DLLs do not contain code.
LoadLibrary can be used to doing the following:
- Map a DLL module and return a handle that can be used in GetProcAddress to get the address of a DLL function. You need to use FreeLibrary on 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 FindResource or LoadResource.
Do not use LoadLibrary to run a .exe file. Use the CreateProcess function.
If the module is a DLL not already mapped for the calling process, the system calls the DLL's DllMain function with the DLL_PROCESS_ATTACH value.
In Windows CE, 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 LoadLibrary function.
When Windows CE loads a DLL, all path information is ignored when determining if the DLL is already loaded. This means that a DLL with the same name but a different path can only be loaded once. In addition, a module ending with the extension .cpl is treated as if the extension is .dll.
It is not safe to call LoadLibrary from DllMain.
Module handles are not global or inheritable. A call to LoadLibrary by 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 LoadLibrary for 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 LoadLibrary is made on Sample.cpl, the operating system will not load Sample.cpl, but instead will again load Sample.dll.
A similar limitation exists for modules with the same name but residing in different directories. For example, if LoadLibrary is called on \\Windows\Sample.dll, and then LoadLibrary is called on \\MyDir\Sample.dll, \\Windows\Sample.dll will simply be reloaded.
If no file name extension is specified in the lpLibFileName parameter, 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 CE searches the following path for the module:
- The absolute path specified by the lpLibFileName parameter
- 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 LoadLibrary and CreateProcess:
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 SystemPath value must not exceed 260 characters. If it does, the path is ignored.
A change to the SystemPath key does not take effect until a Windows CE–based device is reset.
Requirements
OS Versions: Windows CE 1.0 and later.
Header: Winbase.h.
Link Library: Coredll.lib.
See Also
FindResource | LoadResource | CreateProcess | DllMain | FreeLibrary | GetProcAddress | Loader | MODULES Section | Romimage
Send Feedback on this topic to the authors