| HANDLE LoadLibrary(lpszLibFile) | |||||
| LPCTSTR lpszLibFile; | /* address of library-file name | */ | |||
The LoadLibrary function loads the specified library module.
lpszLibFile
Points to a null-terminated string that names the library file to be loaded. If the string does not contain a path, Windows searches for the library in the directories listed in the Comments section.
The return value identifies the loaded library module if the function is successful. Otherwise, it is NULL. Use the GetLastError function to obtain extended error information.
The LoadLibrary function may be used as either a wide-character function (where text arguments must use Unicode) or an ANSI function (where text arguments must use characters from the Windows 3.x character set installed).
It is important to note that module handles are not global, in that a LoadLibrary call by one application does not produce a handle that another application can use, say in calling GetProcAddress. The other application would need to do its own call to LoadLibrary for the module before calling GetProcAddress. A module handle is only valid in the context of a process after the module has been loaded into that process, either as a result of an explicit call to LoadLibrary or as a result of an implicit call caused by a loadtime dynamic link to an entry point in the module.
The library file name does not need to specify an extension. If one is not specified, then the default library file extension, .DLL, is used (note that this is different than Win16. Under Win16 specifying no extension would not cause “.DLL” to be appended to the name. To get Win16 behavior, if the module name has no extension, the caller must supply a trailing “.”).
The library file name does not need to specify a directory path. If one is specified, then the specified file must exist. If a path is not specified, this function will look for the library file using the following Windows search path:
1.The Windows system directory
2.The current process image file directory
3.The current directory
4.The Windows directory
5.The directories listed in the PATH environment variable
The first directory searched is the directory that contains the image file that was used to create the current process (see CreateProcess). This allows private dynamic link library files associated with an application to be found without having to add the application's installed directory to the PATH environment variable.
The image file loader optimizes the search by remembering for each loaded library module that unqualified module name that was searched for when a module was loaded into the current process the first time. This unqualified name has nothing to do with the module name that is stored within the library module itself, as specified by the NAME keyword in the .DEF file. This is a change from the Windows 3.1 behavior, where the search was optimized by comparing to the name within the library module itself, which could lead to a confusing result if the internal name differed from the external file name.
Once a fully qualified path name to a library module file is obtained, a search is made to see if that library module file has been loaded into the current process. The search is case insensitive and includes the full path name of each library module file. If a match is found for the library module file, then it has already been loaded into the current process, so this function just increments the reference count for the module and returns the module handle for that library.
Otherwise, this is the first time the specified module has been loaded for the current process, so the library module's DLL Instance Initialization entry point will be called.
FreeLibrary, LoadModule, FreeModule