SAMPLE: How to Limit an MFC Application to a Single Instance

• The Microsoft Foundation Classes (MFC) included with:

      - Microsoft Visual C++ for Windows, versions 1.0, 1.5, 1.51, 1.52
      - Microsoft Visual C++ 32-bit Edition, version 1.0, 2.0, 2.1
  

SUMMARY

The ONETIME sample application demonstrates how to limit a Microsoft Foundation Class Library (MFC) application to a single instance.

NOTE: The technique shown in this article will not work with MFC versions 4.0 and later because MFC window classes are not pre-registered in these versions. A similar technique is used in the ONET32 sample that was written specifically for MFC versions 4.0 and later. For details, please see the following article in the Microsoft Knowledge Base:

   ARTICLE-ID: Q141752
   TITLE     : SAMPLE: Limiting 32-bit Applications to a Single Instance

 ~ Onetime.exe (size: 33906 bytes) 

   ARTICLE-ID: Q119591
   TITLE     : How to Obtain Microsoft Support Files from
               Online Services

MORE INFORMATION

There are several ways to limit a Windows-based application to a single instance. This sample program uses a technique where a custom window class is registered for the application’s main frame window. In subsequent instances, CWinApp::InitInstance() searches for this window class and then activates the prior instance.

This technique was used because it is fairly easy to implement and is portable to the Win32 application programming interface (API). Because the BringWindowToTop() function works differently in Win32 from 16-bit Windows, the SetForegroundWindow() function should be used instead of BringWindowToTop() in applications that are based on Win32 only.

REMINDER: The following ONETIME technique will not work with MFC versions 4.0 and later because the window classes are not pre-registered. A similar technique is used in the ONET32 sample, which was written specifically for MFC versions 4.0 and later. For details, please see the following article in the Microsoft Knowledge Base:

   ARTICLE-ID: Q141752
   TITLE     : SAMPLE: Limiting 32-bit Applications to a Single Instance

Technique Used in the ONETIME Sample

The following code fragments show the essential requirements of this technique:

Sample code to override CWinApp::InitApplication() to register the custom window class:

   BOOL COnetimeApp::InitApplication()
   {

     // Base class version actually does nothing.
     CWinApp::InitApplication();

     WNDCLASS wndcls;

     // Start with NULL defaults.
     memset(&wndcls, 0, sizeof(WNDCLASS));

     // Retrieve WNDCLASS structure for default window class.
     ::GetClassInfo(AfxGetInstanceHandle(),"AfxFrameOrView",&wndcls);

     // Give new class a unique name.
     wndcls.lpszClassName = "MyNewClass";

     // Register new class and return result from ::RegisterClass().
     return ::RegisterClass(&wndcls);

   }

   BOOL COnetimeApp::InitInstance()
   {

     // If this isn't the first instance, return FALSE
     // immediately. FirstInstance() will have already
     // activated the previous instance.

     if (!FirstInstance())
       return FALSE;

     SetDialogBkColor(); // Set dialog box background color to gray.
        .
        . // Continue with normal InitInstance code...
        .
   }

   BOOL COnetimeApp::FirstInstance()
   {
     CWnd *PrevCWnd, *ChildCWnd;

     // Determine if another window with our class name exists...
     if (PrevCWnd = CWnd::FindWindow("MyNewClass",NULL))
     {
       // if so, does it have any popups?
       ChildCWnd=PrevCWnd->GetLastActivePopup();

       // Bring the main window to the top.
       PrevCWnd->BringWindowToTop();

       // If iconic, restore the main window.
       if (PrevCWnd->IsIconic())
          PrevCWnd->ShowWindow(SW_RESTORE);

       // If there was an active popup, bring it along too
       if (PrevCWnd != ChildCWnd)
          ChildCWnd->BringWindowToTop();

       // Return FALSE. This isn't the first instance
       // and you finished activating the previous one.
       return FALSE;
     }
     else
       return TRUE;  // First instance. Proceed as normal.
   }