GetModuleHandleEx Function

Retrieves a module handle for the specified module. The module must have been loaded by the calling process.

Syntax

C++ 
BOOL WINAPI GetModuleHandleEx(
  __in      DWORD dwFlags,
  __in_opt  LPCTSTR lpModuleName,
  __out     HMODULE *phModule
);

Parameters

dwFlags [in]

This parameter can be one or more of the following values.

ValueMeaning
0

Increment the reference count. This is the default case.

The caller must use the FreeLibrary function when they have finished using the module handle.

GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS
0x00000004

The lpModuleName parameter is an address in the module.

GET_MODULE_HANDLE_EX_FLAG_PIN
0x00000001

The module stays loaded until the process is terminated, no matter how many times FreeLibrary is called.

This option cannot be used with GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT.

GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT
0x00000002

Do not increment the reference count for the module. This option is equivalent to the behavior of GetModuleHandle.

This option cannot be used with GET_MODULE_HANDLE_EX_FLAG_PIN.

 

lpModuleName [in, optional]

The name of the loaded module (either a .dll or .exe file), or a pointer to an address in the module (if dwFlags is GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS).

For a module name, 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. The string does not have to specify a path. When specifying a path, be sure to use backslashes (\), not forward slashes (/). The name is compared (case independently) to the names of modules currently mapped into the address space of the calling process.

If this parameter is NULL, the function returns a handle to the file used to create the calling process (.exe file).

phModule [out]

A handle to the specified module. If the function fails, this parameter is NULL.

The GetModuleHandleEx function does not retrieve handles for modules that were loaded using the LOAD_LIBRARY_AS_DATAFILE flag. For more information, see LoadLibraryEx.

Return Value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, see GetLastError.

Remarks

The handle returned is not global or inheritable. It cannot be duplicated or used by another process.

If lpModuleName does not include a path and there is more than one loaded module with the same base name and extension, you cannot predict which module handle will be returned. To work around this problem, you could specify a path, use side-by-side assemblies, or specify a memory location rather than a DLL name in the lpModuleName parameter.

If dwFlags contains GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, use care when passing the handle to the FreeLibrary function, because doing so can cause a DLL module to be unmapped prematurely.

If dwFlags contains GET_MODULE_HANDLE_EX_UNCHANGED_REFCOUNT, this function must 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. For example, a thread retrieves a module handle, but before it uses the handle, a second thread frees the module. If the system loads another module, it could reuse the module handle that was recently freed. Therefore, first thread would have a handle to a module different than the one intended.

To compile an application that uses this function, define _WIN32_WINNT as 0x0501 or later. For more information, see Using the Windows Headers.

Requirements

Minimum supported clientWindows XP
Minimum supported serverWindows Server 2003
HeaderWinbase.h (include Windows.h)
LibraryKernel32.lib
DLLKernel32.dll
Unicode and ANSI namesGetModuleHandleExW (Unicode) and GetModuleHandleExA (ANSI)

See Also

Dynamic-Link Library Functions
FreeLibrary
GetModuleFileName
LoadLibrary
LoadLibraryEx

Send comments about this topic to Microsoft

Build date: 11/19/2009



Community Content

Thomas Lee
Incrementing the reference count without GetModuleHandleEx

A backwards-compatible replacement of GetModuleHandleEx(0, ...), i.e. a way to resolve the name of a module and increment its reference count: 

HMODULE ReferenceModuleByHandle(HMODULE hModule)
{
    TCHAR szModuleFileName[MAX_PATH + 1];
  

    if(GetModuleFileName(hModule, szModuleFileName, ARRAYSIZE(szModuleFileName) - 1))
        return LoadLibrary(szModuleFileName);
    else
        return NULL;
}
  
HMODULE ReferenceModuleByName(LPCTSTR lpModuleName)
{
    return ReferenceModuleByHandle(GetModuleHandle(lpModuleName));
}

Thomas Lee
Backwards-compatible GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS (using PSAPI)

Resolving and referencing a DLL by address in a backwards-compatible, using PSAPI (equivalent to GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS):

HMODULE GetModuleHandleByAddress(HANDLE hProc, LPVOID lpAddress)
{
    HANDLE hHeap = GetProcessHeap();
    HMODULE * hmodules = NULL;
    DWORD cb = 0;

    for(;;)
    {
        DWORD cbNeeded = 0;

        if(!EnumProcessModules(hProc, hmodules, cb, &cbNeeded))
            return NULL;

        if(cb >= cbNeeded)
        {
            cb = cbNeeded;
            break;
        }

        PVOID p = HeapAlloc(hHeap, 0, cbNeeded);
        HeapFree(hHeap, 0, hmodules);

        if(p == NULL)
            return NULL;

        hmodules = (HMODULE *)p;
        cb = cbNeeded;
    }

    DWORD i = 0;
    DWORD ccModules = cb / sizeof(HMODULE);
    HMODULE hm = NULL;

    for(; i < ccModules; ++ i)
    {
        MODULEINFO modinfo;

        if(!GetModuleInformation(hProc, hmodules[i], &modinfo, sizeof(modinfo)))
            continue;

        if(lpAddress < modinfo.lpBaseOfDll)
            continue;

        if((ULONG_PTR)lpAddress >= ((ULONG_PTR)modinfo.lpBaseOfDll + modinfo.SizeOfImage))
            continue;

        hm = (HMODULE)modinfo.lpBaseOfDll;
        break;
    }
  

    if(i == ccModules && hm == NULL)
        SetLastError(ERROR_MOD_NOT_FOUND);

    HeapFree(hHeap, 0, hmodules);

    return hm;
}
  

HMODULE ReferenceModuleByAddress(LPVOID lpAddress)
{
    return ReferenceModuleByHandle(GetModuleHandleByAddress(GetCurrentProcess(), lpAddress));
}

See the above comment for the definition of ReferenceModuleByHandle.


Thomas Lee
Incrementing the reference count without GetModuleHandleEx
At least in Vista SP1 where I tested it, LoadLibrary( GetModuleFileName) fails with error 126 if the original DLL has been renamed. It succeeds if not the full path but only the base name is used.


SDX3000
Clarification
The name of the loaded module (either a .dll or .exe file), or a pointer to an address in the module (if dwFlags is GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS).

NOTE: Do not pass in a pointer to an address - you need to pass an "address in the module" directly. For example...

GetModuleHandleEx(GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS, (LPCTSTR)&_hModule, &_hModule); //Where _hModule is a member variable

Page view tracker