LoadLibrary

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.

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

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 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. See the Remarksfor more information.

Return Values

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

Remarks

LoadLibrarycan be used to map a DLL module and return a handle that can be used in GetProcAddressto get the address of a DLL function. LoadLibrarycan also be used to 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.

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 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 LoadLibraryfunction. 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 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 filename, given that the extensions are different. These effectively have the same "module" name. For example, if LoadLibraryis 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 LoadLibraryis called on "\\Windows\Sample.dll", and then LoadLibraryis called on "\\MyDir\Sample.dll", "\\Windows\Sample.dll" will simply be reloaded.

If no filename extension is specified in the lpLibFileNameparameter, 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.

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:

1. The absolute path specified by the lpLibFileNameparameter
2. ROM for statically-linked .DLL files
3. The .EXE launch directory
4. The windows (\windows) directory
5. The root (\) directory
6. An OEM-dependent directory
7. The OEM-defined shell (\ppshell) directory—Platform Builder users only.
8. In Windows CE, version 3.0 searches the ROM for statically-linked DLL files last.

   Windows CE versions 1.0 through 2.01 search the following path for the module:

   1. The root directory of the PC Card RAM expansion card, if one exists.
   2. The windows directory (\Windows).
   3. The root directory (\).

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

      HKEY_LOCAL_MACHINE\Loader
      "SystemPath"=multi_sz:"\\path1\\"
      "\\path2\\"

      For efficiency, the path is searched before CESH but after the ROM and built in file systems. Note also that the path is only searched if path of the file being looked for is not explicitly specified.

      The total length of the SystemPathvalue cannot exceed 260 characters, or the path will be completely ignored. A change to the SystemPathkey does not take effect until a Windows CE-based device is reset.

      Requirements

      Runs On	Versions	Defined in	Include	Link to
      Windows CE OS	1.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

      FindResource, FreeLibrary, GetProcAddress, LoadResource

      
      

      ---

      Last updated on Friday, May 26, 2006

      © 2004 Microsoft Corporation. All rights reserved.