This function maps the specified .DLL file into the address space of the calling process.
At a Glance
| Header file: | Winbase.h |
| Windows CE versions: | 1.0 and later |
Syntax
HINSTANCE LoadLibrary( LPCTSTR lpLibFileName );
Parameters
lpLibFileName
Pointer to a null-terminated string that names the .DLL file. The name specified is the filename 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. See the Remarks for more information.
Return Values
A handle to the module indicates success. NULL indicates failure. To get extended error information, call GetLastError.
Windows CE Remarks
Two different modules cannot have the same filename, given that 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.
A search path to the executable module cannot be specified. Unless the full path to the module is specified, Windows CE versions 2.10 and later search the following path for the module:
Windows CE versions 1.0 through 2.01 search the following path for the module:
Remarks
LoadLibrary can be used to map a DLL module and return a handle that can be used in GetProcAddress to get the address of a DLL function. Do not use LoadLibrary to load or "run" a .exe file.
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 then it is mapped into each processes 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 if ".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.
If no filename extension is specified in the lpLibFileName parameter, the default library extension .DLL is appended. However, the filename string can include a trailing point character (.) to indicate that the module name has no extension.
When no path is specified, the function searches for loaded modules whose base name matches the base name of the module to be loaded. If the name matches, the load succeeds. Otherwise, the function searches for the file in the following sequence:
Windows CE versions 1.0 through 2.01 search the following path for the module:
See Also