Allowing Only One Application Instance on Win32s

• Microsoft Win32s, versions 1.30, 1.30a, 1.30c

SUMMARY

The entry point for both Windows-based and Win32-based applications is:

   int WinMain( hInstance, hPrevInstance, lpszCmdLine, nCmdShow )

   HINSTANCE hInstance;        /* Handle of current instance  */
   HINSTANCE hPrevInstance;    /* Handle of previous instance */
   LPSTR lpszCmdLine;          /* Address of command line     */
   int nCmdShow;               /* Show state of window        */

However, in a Win32-based application, hPrevInstance is always NULL. Therefore, you cannot determine if another instance of your application has been started simply by examining hPrevInstance. This article gives you a method you can use.

MORE INFORMATION

Use one of the following four methods to determine if there is an existing application instance on Win32s:

• Synchronize with a named object, such as a file mapping.

  -or-

• Synchronize with a global atom.

  -or-

• Synchronize with a private message.

  -or-

• Use FindWindow() to check for the application.

Using a File Mapping

Using a file mapping works well on any Win32 platform. The global atom is a cheaper resource, whereas a file mapping will cost a page of memory. A private message is good if you want to inform the first instance that the user attempted to start a second instance, and then let it handle the request -- post a message, become the active application, and so on.

NOTE: You need to clean up before terminating the second instance. FindWindow() doesn't require cleanup, but this method will not work as reliably in a preemptive multitasking environment, such as Windows NT, because you can get in a race condition.

The following code fragment demonstrates how a file mapping can be used to allow only one instance of a Win32-based application. This code should avoid any race conditions. Place this code at the beginning of WinMain().

The code creates a file mapping named MyTestMap using CreateFileMapping(). If MyTestMap already exists, then you know that there is already a running instance of this application. A similar technique would be used with a global atom.

Sample Code

   HANDLE hMapping;

   hMapping = CreateFileMapping( (HANDLE) 0xffffffff,
                                 NULL,
                                 PAGE_READONLY,
                                 0,
                                 32,
                                 "MyTestMap" );
   if( hMapping )
   {
      if( GetLastError() == ERROR_ALREADY_EXISTS )
      {
      //
      // Display something that tells the user
      // the app is already running.
      //
         MessageBox( NULL, "Application is running.", "Test", MB_OK );
         ExitProcess(1);
      }
   }
   else
   {
   //
   // Some other error; handle error.
   //
      MessageBox( NULL, "Error creating mapping", "Test", MB_OK );
      ExitProcess(1);
   }