Home / MSDN / Documentation / Windows / API Reference / Win32 / Functions / GetModuleHandleEx

GetModuleHandleEx function

Applies to: Windows, Server Core

Syntax


BOOL GetModuleHandleExA(
  [in]           DWORD   dwFlags,
  [in]           LPCSTR  lpModuleName,
  [out]          HMODULE *phModule
);

BOOL GetModuleHandleExW(
  [in]           DWORD   dwFlags,
  [in]           LPCWSTR lpModuleName,
  [out]          HMODULE *phModule
);

Note: This function is declared in libloaderapi.h.

Parameters

Parameter Type Description
dwFlags DWORD A flag that indicates whether the handle to be returned is a handle to the module or a handle to the process. This parameter can be one or more of the following values:
  • GET_MODULE_HANDLE_EX_CLOSE_MODULE_HANDLE: Decrements the reference count on the module. For more information, see Remarks.
  • GET_MODULE_HANDLE_EX_PIN: Increments the reference count on the module. The system does not unload the module until all references to it have been removed.
lpModuleName LPCSTR or LPCWSTR The name of the loaded module (.dll or .exe). The name is not case-sensitive. If this parameter is NULL, the function returns a handle to the module that contains the calling thread.

If dwFlags is GET_MODULE_HANDLE_EX_PIN or GET_MODULE_HANDLE_EX_CLOSE_MODULE_HANDLE, lpModuleName cannot be NULL.
phModule HMODULE* A pointer to a variable that receives the module handle.

Return value

TRUE The function succeeded. The handle to the specified module is returned in the phModule parameter.
FALSE The function failed. To get extended error information, call GetLastError.

Remarks

The GetModuleHandleEx function retrieves a handle to a module that has been mapped into the address space of the calling process. For more information, see Mapping Modules into Address Space.

Unlike the GetModuleHandle function, GetModuleHandleEx allows you to specify whether to increment the module's reference count. This is useful for ensuring that a module is not unloaded while your application is using it.

If dwFlags includes GET_MODULE_HANDLE_EX_CLOSE_MODULE_HANDLE, the reference count for the module is decremented. This is typically done after you have obtained a handle to the module and copied the necessary information from it, or if you no longer need the module to remain loaded.

If dwFlags includes GET_MODULE_HANDLE_EX_PIN, the reference count for the module is incremented. This ensures that the module will not be unloaded by another thread or process while you are using its handle.

If lpModuleName is NULL, GetModuleHandleEx returns a handle to the module that contains the calling thread. This is useful for the calling module to obtain its own handle.

Example

The following example demonstrates how to get a handle to the current module and then immediately decrement its reference count:


HMODULE hModule = NULL;
TCHAR szModuleName[] = TEXT("MyModule.dll"); // Replace with your module name

if (GetModuleHandleEx(
    GET_MODULE_HANDLE_EX_CLOSE_MODULE_HANDLE,
    szModuleName,
    &hModule))
{
    // Handle obtained and reference count decremented.
    // Now hModule can be used, but the module may be unloaded later.
    // Do not rely on the handle being valid for an extended period.
    // If you need the module to stay loaded, use GET_MODULE_HANDLE_EX_PIN.
}
else
{
    // Handle retrieval failed.
    DWORD dwError = GetLastError();
    // Handle error.
}

Requirements

Minimum supported client Windows 2000 Professional
Minimum supported server Windows 2000 Server
Header libloaderapi.h (include windows.h)
Library Kernel32.lib
DLL Kernel32.dll
Unicode and ANSI versions GetModuleHandleExW (Unicode) and GetModuleHandleExA (ANSI)

See also