CInstanceChecker v1.18 A C++ class to
implement single instance apps
Welcome to CInstanceChecker, a C++ class to make your app into
a single instance. Limiting your app to single instance is more tricky in Win32
with the removal of the hPrevInstance parameter from WinMain and the introduction
of separate address spaces.
There are numerous examples already out there of making your app single instance,
but some published code on the Internet require knowledge of undocumented or heavy
Other methods such as using FindWindow, FindWindowEx are not 100% bullet proof
due to the pre-emptive Win32 environment.
This class internally uses a memory mapped file (MMF) into which the handle of
the main window of your application is stuffed. When a second instance of your app
is run, it detects that the memory mapped file exists, gets the window handle of
the first instance from the MMF and reactivates the old window.
The enclosed zip file contains the
CInstanceChecker source code and a simple MFC framewnd based app as well as a MFC
dialog based app which demonstrates all
the functionality of the class. For further details on how to use the class have
a look at the BOOL CMyApp::InitInstance() function and the included documentation.
- You are allowed to include the source code in any product (commercial, shareware,
freeware or otherwise) when your product is released in binary form.
- You are allowed to modify the source code in any way you want except you
cannot modify the copyright details at the top of each module.
- If you want to distribute source code with your application, then you are
only allowed to distribute versions released by the author. This is to maintain
a single distribution point for the source code.
V1.0 (29 July 1998)
V1.01 (27 March 2000)
- Now ships with a VC 5 workspace.
- Fixed a potential handle leak where the file handle m_hPrevInstance was
not being closed under certain circumstances.
- The remaining changes were made by Neville Franks.
- Changed #pragma error in sinstance header file to #pragma message. Former
wouldn't compile under VC6
- Replaced above #pragma with #include.
- Added TrackFirstInstanceRunning(), MakeMMFFilename()
- Split PreviousInstanceRunning() up into separate functions so we can call
it without needing the MainFrame window.
- Changed ActivatePreviousInstance() to return hWnd.
V1.02 (28 March 2000)
- Minor update to the documentation.
V1.03 (15 May 2000)
- Serialized access to all of the CSingleInstance class to prevent race conditions
which can occur when you app is programmatically spawned.
V1.04 (17 May 2000)
- Now includes a dialog app to demo how to use the code in a dialog based
app. Also updated the documentation re dialog based apps.
V1.05 (1 January 2001)
- Added a number of asserts to CInstanceChecker::ActivatePreviousInstance
- Now includes copyright message in the source code and documentation
V1.06 (11 January 2001)
- Now allows multiple calls to PreviousInstanceRunning without ASSERTing
- Removed some unnecessary VERIFY's from ActivatePreviousInstance
- Made the MMF filename used modifiable via a virtual function GetMMFFilename
- Made the window to track modifiable via a virtual function GetWindowToTrack
- Made destructor virtual since the introduction of other virtual functions
in the class
- Removed a number of unnecessary verifies
- Changed the meaning of the return value from TrackFirstInstanceRunning
V1.07 (17 June 2001)
- Moved most of the code from CInstanceChecker::CInstanceChecker to CInstanceChecker::ActivateChecker.
This allows client code to turn on or off the instance checking code easily.
Thanks to Anders Rundegren for this addition.
V1.08 (21 July 2001)
- Fixed a bug in the sample dialog app which was causing the app to crash.
The important change is to make sure "m_pMainWnd" is set to NULL before you
return from InitInstance. See the module "sinstancedlg.h" or the Usage section
above for the correct way to use the code in a dialog based app.
V1.09 (31 August 2001)
- Made the name of the mutex which the class uses to serialize access to itself
a parameter to the constructor. That way multiple independent apps do not block
each other while they are calling into the CSingleInstance class. Thanks to
Eugene Shmelyov for spotting this problem.
V1.10 (23 March 2002)
- Provided a QuitPreviousInstance method. Thanks to Jon Bennett for providing
1 May 2002
- Updated code snippets in documentation to describe how to use the class.
V1.11 (30 October 2002)
- The name of the internal memory mapped file is now based on the Mutex name
rather than the application name. An example: a client was writing a webcam
application and wanted it to run with multiple configuration for multiple camera
support. So the app can run multiple times as long as a special configuration
is given on the command line. But for that configuration only one instance is
allowed. Using the application name for the memory mapped file was tying the
single instance to the app rather than the unique mutex name. Thanks to Frank
Fesevur for this nice update.
V1.12 (6 February 2003)
- Was missing a call to ReleaseLock in CInstanceChecker::ActivatePreviousInstance.
Thanks to Pierrick Ingels for reporting this problem.
V1.13 (9 May 2004)
- Updated the copyright details.
- Extended CInstanceChecker::ActivatePreviousInstance to now allow the command
line of the
second app to be passed to the original app. By default the parameter is NULL,
you get the original behaviour which just activates the previous instance. To
respond to this
information you should add the following to your mainfrm module:
afx_msg LRESULT OnCopyData(WPARAM, LPARAM);
LRESULT CMyFrameWnd::OnCopyData(WPARAM wParam, LPARAM lParam)
COPYDATASTRUCT* pCDS = reinterpret_cast<COPYDATASTRUCT*>(lParam);
TCHAR* pszCmdLine = static_cast<TCHAR*>(pCDS->lpData);
//DO SOMETHING with pszCmdLine here such as call AfxGetApp()->OpenDocumentFile(pszCmdLine);
Also hook up your onCopyData to the windows message map using
Thanks to Ingo H. de Boer for providing this nice update.
- Following a discussion on the Codeproject.com discussion forum for CSingleInstance
on what exactly a single instance app means (See
Lohmann has produced a simple function called CreateUniqueName which given a
number of settings as flags, will produce a name which is unique. This code
can be downloaded at
http://www.losoft.de/code/SingleInstance.zip. You can then use this name
in the constructor for CInstanceChecker. The concept of a single instance app
is complicated by the concept of Window stations and desktops as used by NT
Services and Windows Terminal Services. In addition you might want to allow
your program to be run once per user.
V1.14 (30 May 2005)
- Fix for a crash where CWnd::GetLastActivePopup can sometimes return a NULL
pointer. Thanks to Dominik Reichl for reporting this bug.
V1.15 (7 July 2006)
- Updated copyright details.
- Addition of CSINGLEINSTANCE_EXT_CLASS and CSINGLEINSTANCE_EXT_API which
allows the class to be easily used in an extension DLL.
- Removed derivation from CObject as it was not really needed.
- Updated the documentation to use the same style as the web site.
- Code now uses newer C++ style casts instead of C style casts.
- Fixed a number of level 4 warnings in the sample app.
- Updated code to compile cleanly using VC 2005.
V1.16 (17 March 2007)
- Updated copyright details.
- Optimized _INSTANCE_DATA constructor code
- Reworked how the method CInstanceChecker::GetMMFFilename creates the name
of the memory mapped filename the code requires for sharing. Now the main instance
name appears before the hard coded string. This ensures that the CInstanceChecker
class works correctly for terminal sessions i.e. kernel objects prefixed with
the value "Local\". Thanks to Mathias Berchtold for reporting this issue.
- Updated the sample app code to clean compile on VC 2005.
- QuitPreviousInstance now uses GetLastActivePopup API to ensure it posts
the WM_QUIT message to the correct window of the previous instance.
V1.17 (2 February 2008)
- Updated copyright details
- Removed VC 6 style classwizard comments from the sample apps code
- Updated ActivatePreviousInstance method to support Win64 compliant data
- ActivatePreviousInstance now takes a "dwTimeout" parameter which it now
uses internally as the timeout when calling SendMessageTimeout instead of SendMessage.
The code now uses SendMessageTimeout instead of SendMessage to ensure we do
not hang if the previous instance itself is hung. Thanks to Paul Shore for suggesting
- Updated the sample apps to clean compile on VC 2008
V1.18 (4 March 2016)
- Updated copyright details.
- Update the sample app project settings to more modern defaults.
- Update the code to clean compile on VC 2010 - 2015
- Added SAL annotations to all the code.
- CInstanceChecker::PreviousInstanceRunning now uses FILE_MAP_READ flag
when attempting to open the file mapping
- The ActivatePreviousInstance method now includes a new HWND
- The sample app which uses a MFC CFrameWnd now shows some text
in the client area to tell end-users what to do to exercise the code.
- After updating the instructions on how to use the class, the code
which referenced an internal _SINSTANCE_DATA global static instance has been
refactored back into the main CInstanceChecker class
- CInstanceChecker::TrackFirstInstanceRunning now takes a HWND
hWindowToTrack parameter. This parameter now eliminates the need for the
- Reworked the internals of the CInstanceChecker class to avoid use
of MFC. Instead now all the class uses ATL replacements for equivalent MFC
- Reworked the internals of the QuitPreviousInstance method.
- Removed the need for the ActivateChecker and GetMMFFilename
- The structure which is put into the memory mapped file now is 8
bytes in size. This is to allow interop between Win32 and Win64 instances of
the same application.
- Refactored the code in ActivatePreviousInstance &
QuitPreviousInstance which finds the previous HWND into a new
- Reworked the code which serializes access to all instances of
CInstanceChecker and in the process removed the need for the mutex which
protects the memory mapped file.