GetModuleHandle

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 returns a module handle for the specified module if the file has been mapped into the address space of the calling process.

HMODULE GetModuleHandle ( LPCTSTR
lpModuleName
);

Parameters

lpModuleName

Pointer to a null-terminated string that contains the name of the module, which must be a .DLL file. If the filename extension is omitted, the default library extension .DLL is appended. The filename string can include a trailing point character (.) to indicate that the module name has no extension.

If this parameter is NULL, GetModuleHandlereturns a handle to the file used to create the calling process.

All paths are ignored; only the file name and extension are used.

The file extensions .DLL and .CPL are treated as identical when comparing module names.

Return Values

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 GetModuleHandleand LoadLibrarycan be used in the same functions—for example, GetProcAddress, FreeLibrary, or LoadResource. The difference between the two functions involves the reference count. LoadLibrarymaps 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 that the reference count is used in FreeLibraryto determine whether to unmap the function from the address space of the process. For this reason, use care when using a handle returned by GetModuleHandlein a call to FreeLibrarybecause doing so can cause a dynamic-link library (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. Before the thread uses the handle in another function, 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

Runs On	Versions	Defined in	Include	Link to
Windows CE OS	2.10 and later	Winbase.h		Coredll.lib, 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.