GetModuleHandleEx

The GetModuleHandleEx function retrieves a handle for the module name specified by parameter lpModuleName in a specified process.

Syntax

BOOL GetModuleHandleEx(
    [in]            DWORD dwFlags,
    [in, optional]  LPCTSTR lpModuleName,
    [out]           HMODULE *phModule,
);

Parameters

[in] dwFlags

This parameter can be zero or one or more of the following values. If the module's reference count is incremented, the caller must use the FreeLibrary function to decrement the reference count when the module handle is no longer needed.

[in, optional] lpModuleName

The name of the loaded module (either an .rtdll or .rtss file), or an address in the module (if dwFlags is GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS).

If the file name extension is omitted for a module name, the default library extension .rtdll is appended. 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 calling process's address space.

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

If parameter is NULL you must use the GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT flag, otherwise the function will fail as you cannot directly increment the reference count to the calling process.

[out] phModule

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

Return Value

If the function succeeds, it returns TRUE. If the function fails, it returns FALSE. Call GetLastError to get extended error information.

Remarks

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

The wRTOS implementation of GetModuleHandleEx differs from Windows behavior in that the current process module does not have its reference count incremented. Attempts to retrieve the module from GetHandleModuleEx return the module, but the reference to that module does not increment.

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 RTDLL name in the lpModuleName parameter.

If dwFlags contains GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, the GetModuleHandleEx function returns a handle to a mapped module without incrementing its reference count. However, if this handle is passed to the FreeLibrary function, the reference count of the mapped module will be decreased. Therefore, do not pass a handle returned by GetModuleHandleEx with GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT to the FreeLibrary function. Doing so can cause an RTDLL 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 when this function returns the handle and when it is used. For example, a thread retrieves a module handle, but a second thread frees the module before it uses the handle. If the system loads another module, it could reuse the module handle that was recently freed. Therefore, the first thread would have a handle to a module different than the one intended.

There is a known limitation in GetHandleModuleEx and GetHandleModule where implicitly loaded DLLs cannot be searched, as they reside in a different handle List.

Requirements