HOWTO: How to Provide Your Own DllMain in an MFC Regular DLL

Retired KB Content Disclaimer

View products that this article applies to.

This article was previously published under Q148791

SUMMARY

By design, MFC Regular DLLs have a default DllMain function provided automatically by MFC. Regular DLLs should not provide their own DllMain. Any initialization which is necessary when the DLL is loaded should be done in the InitInstance member function of the one CWinApp-derived class in the Regular DLL. Deinitialization and termination code should go in the ExitInstance member function.

However, InitInstance is only called by MFC's DllMain when a process attaches (DLL_PROCESS_ATTACH) to the DLL and ExitInstance is called only when a process detaches (DLL_PROCESS_DETACH) from the DLL. If it is necessary to handle thread attachment to and detachment from (DLL_THREAD_ATTACH and DLL_THREAD_DETACH) in MFC Regular DLL, the Regular DLL will need to provide its own DllMain. This article explains how to do it.

Back to the top

MORE INFORMATION

When a Regular DLL is created, the MFC source forcibly links in the code for the source file \Msdev\Mfc\Src\Dllmodul.cpp. Dllmodul.cpp contains most of the code added to a Regular DLL to support MFC in that DLL. One of the most important functions in Dllmodul.cpp is the DllMain function.

To add code to MFC's DllMain, copy the \Msdev\Mfc\Src\Dllmodul.cpp source file to your project directory, and include the copy in your project. This copy of Dllmodul.cpp will be compiled and linked into your DLL instead of the Dllmodul.cpp in the Mfc\Src directory, so changes to the DllMain in it will show up in the final DLL.

The primary caveat is that this is not a recommended solution and should only be used when absolutely necessary. Any changes to the code in Dllmodul.cpp will undoubtedly have unpredictable results. Add code only, do not remove or modify the existing code.

For regular DLLs that use MFC in the Shared Lib, the module state should be set at the beginning of any added code and restored before returning from DllMain. Refer to the sample code in this article for an example of a DllMain that handles the DLL_THREAD_ATTACH and DLL_THREAD_DETACH notifications and properly switches the module state as necessary.

Additional care must be taken when relying on DllMain being called with DLL_THREAD_ATTACH and DLL_THREAD_DETACH because of the following conditions:

When a thread is created in a process, the system calls DllMain with a value of DLL_THREAD_ATTACH for each of the DLLs mapped into into the process. However, if a process has several threads running in it when a new DLL is mapped into it, DllMain isn't called with a DLL_THREAD_ATTACH value for any of the existing threads.
DllMain is not called with a value DLL_THREAD_ATTACH for the process's primary thread.
On thread termination (by a call to ExitThread), DllMain is called with a value of DLL_THREAD_DETACH for each of the DLLs. DllMain is not called with DLL_THREAD_DETACH for any thread unless a thread terminates by calling ExitThread.
If a thread terminates due to a call to TerminateThread, DllMain isn't called with a value DLL_THREAD_DETACH.
It is possible for a thread in a process to call LoadLibrary to load a DLL causing a call to DllMain with DLL_PROCESS_ATTACH, and then on thread termination, cause a call to dllMain with DLL_THREAD_DETACH without ever calling DLL_THREAD_ATTACH. It is therefore best that the thread that calls LoadLibrary also call FreeLibrary.

NOTE: MFC CWnd objects, CDC objects, CMenu objects, GDI objects, and CImageList objects are restricted to a per-thread, per-module basis. In other words, MFC objects created in one module or thread cannot be passed to and/or used in a different module or thread. This has special relevance for any code added to handle DLL_THREAD_ATTACH or DLL_THREAD_DETACH in DllMain because DllMain is called for these reasons with different threads. CWnd objects, for instance, created in DllMain during DLL_PROCESS_ATTACH or in InitInstance will not be valid during DLL_THREAD_ATTACH.

Back to the top

Sample Code

//////////////////////////////////////////////////////////////////// 
// export DllMain for the DLL
// Add code in the specified sections only.
// Remove code at your own risk.
extern "C"
BOOL WINAPI DllMain(HINSTANCE hInstance, DWORD dwReason, LPVOID
/*lpReserved*/)
{
   if (dwReason == DLL_PROCESS_ATTACH)
   {
// ... Code abbreviated from DLLMODUL.CPP
   }
   else if (dwReason == DLL_PROCESS_DETACH)
   {
// ... Code abbreviated from DLLMODUL.CPP
   }
// NEW CODE ADDED HERE
// -------------------
   else if (dwReason == DLL_THREAD_ATTACH)
   {
#ifdef _AFXDLL
      // set module state
      ASSERT(AfxGetThreadState()->m_pPrevModuleState == NULL);
      AfxGetThreadState()->m_pPrevModuleState =
         AfxSetModuleState(AfxGetStaticModuleState());
#endif
      // ADD DLL_THREAD_ATTACH CODE HERE
      // Remember that this won't necessarily be called for
      // every thread in the process into which this DLL is mapped
      // Threads created by the process BEFORE the DLL
      // was loaded will not call into DLL_THREAD_ATTACH.

#ifdef _AFXDLL
      // restore previously-saved module state
     VERIFY(AfxSetModuleState(AfxGetThreadState()->m_pPrevModuleState)
             == AfxGetStaticModuleState());
        DEBUG_ONLY(AfxGetThreadState()->m_pPrevModuleState = NULL);
#endif

   }
   else if (dwReason ==DLL_THREAD_DETACH)
   {
#ifdef _AFXDLL
      // set module state
      ASSERT(AfxGetThreadState()->m_pPrevModuleState == NULL);
      AfxGetThreadState()->m_pPrevModuleState =
         AfxSetModuleState(AfxGetStaticModuleState());
#endif
      // ADD DLL_THREAD_DETACH CODE HERE

#ifdef _AFXDLL
      // restore previously-saved module state
   VERIFY(AfxSetModuleState(AfxGetThreadState()->m_pPrevModuleState)
          == AfxGetStaticModuleState());
      DEBUG_ONLY(AfxGetThreadState()->m_pPrevModuleState = NULL);
#endif
   }

   return TRUE;
}

Back to the top

REFERENCES

For more information on MFC objects being thread local, please see the following article in the Microsoft Knowledge Base:

147578 (http://support.microsoft.com/kb/147578/EN-US/ ) CWnd Derived MFC Objects and Multi-threaded Applications

For more information on module state information, please see the following article in the Microsoft Knowledge Base:

140850 (http://support.microsoft.com/kb/140850/EN-US/ ) How to Convert DLLTRACE to Use MFC in Shared Library

For more information on why you shouldn't create a thread in DllMain, please see the following article in the Microsoft Knowledge Base:

142243 (http://support.microsoft.com/kb/142243/EN-US/ ) PRB: Cannot Create an MFC Thread During DLL Startup

Back to the top

APPLIES TO

Microsoft Foundation Class Library 4.2, when used with:

Microsoft Visual C++ 4.0 Standard Edition

Back to the top

kbarchitecture kbcode kbdll kbhowto KB148791

Back to the top

Retired KB Content Disclaimer

This article was written about products for which Microsoft no longer offers support. Therefore, this article is offered "as is" and will no longer be updated.

Back to the top