GetModuleHandle
A version of this page is also available for
4/8/2010
This function returns a module handle for the specified module if the file is mapped into the address space of the calling process.
Syntax
HMODULE GetModuleHandle(
LPCTSTR lpModuleName
);
Parameters
lpModuleName
[in] Pointer to a null-terminated string that contains the name of the module, which must be a DLL file.If the file name extension is omitted, the default library extension .dll is appended.
The file name string can include a trailing point character (.) to indicate that the module name has no extension.
If this parameter is NULL, GetModuleHandle returns a pseudo handle to the current process. All paths are ignored; only the file name and extension are used. A pseudo handle is a special constant that is interpreted as the current thread handle. The calling thread can use this handle to specify itself when a thread handle is required.
The file extensions .dll and .cpl are treated as identical when comparing module names.
Return Value
A handle to the specified module indicates success. NULL indicates failure. To get extended error information, call GetLastError.
Remarks
The returned handle is not global, inheritable, or duplicative, and it cannot be used by another process.
The handles returned by GetModuleHandle and LoadLibrary can be used in the same functions — for example, GetProcAddress, FreeLibrary, or LoadResource.
The difference between the two functions involves the reference count:
- LoadLibrary maps the module into the address space of the calling process, if necessary, and increments the module's reference count, if it is already mapped.
- GetModuleHandle, however, returns the handle to a mapped module without incrementing its reference count.
Note
The reference count is used in FreeLibrary to determine whether to unmap the function from the address space of the process. For this reason, use care when using a handle returned by GetModuleHandle in a call to FreeLibrary. Doing so can cause a DLL module to be unmapped prematurely.
This function must also be used carefully in a multithreaded application.
There is no guarantee that the module handle remains valid between the time this function returns the handle and the time it is used by another function.
For example, a thread might retrieve a module handle by calling GetModuleHandle, but before the thread uses the handle, a second thread could free the module and the system could load another module, giving it the same handle as the module that was recently freed. The first thread would then be left with a module handle that refers to a module different from the one intended.
Requirements
| Header | winbase.h |
| Library | coredll.lib, Nk.lib |
| Windows Embedded CE | Windows CE 2.10 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |
See Also
Reference
DLL Functions
FreeLibrary
GetProcAddress
LoadLibrary