274 lines
19 KiB
C++
274 lines
19 KiB
C++
// ==========================================================================
|
||
// Class Specification : COXInstanceManager
|
||
// ==========================================================================
|
||
|
||
// Header file : OXInstanceManager.h
|
||
|
||
// Version: 9.3
|
||
|
||
// This software along with its related components, documentation and files ("The Libraries")
|
||
// is ?1994-2007 The Code Project (1612916 Ontario Limited) and use of The Libraries is
|
||
// governed by a software license agreement ("Agreement"). Copies of the Agreement are
|
||
// available at The Code Project (www.codeproject.com), as part of the package you downloaded
|
||
// to obtain this file, or directly from our office. For a copy of the license governing
|
||
// this software, you may contact us at legalaffairs@codeproject.com, or by calling 416-849-8900.
|
||
|
||
// //////////////////////////////////////////////////////////////////////////
|
||
|
||
// Properties:
|
||
// NO Abstract class (does not have any objects)
|
||
// YES Derived from CObject
|
||
|
||
// NO Is a Cwnd.
|
||
// NO Two stage creation (constructor & Create())
|
||
// NO Has a message map
|
||
// NO Needs a resource (template)
|
||
|
||
// NO Persistent objects (saveable on disk)
|
||
// NO Uses exceptions
|
||
|
||
// //////////////////////////////////////////////////////////////////////////
|
||
|
||
// Desciption :
|
||
// This class organizes several instances of the same program.
|
||
// A list is kept with all the instances IDs (which are actual process IDs)
|
||
// This way you can check the number of running instances, send messages to
|
||
// their main window, close isntances etc.
|
||
|
||
// A framework to exchange (share) data between these instances is also implemented
|
||
// The size of this additional data must be supplied to the constructor of this class
|
||
// The data can be access through : GetAdditionalDataSize() and GetAdditionalData()
|
||
// You may use a supplied mutex to synchronize access to this data (GetAdditionalDataMutex())
|
||
|
||
// To allow only one instance of your application :
|
||
// - Create a global object of this class (supply a unique application name!)
|
||
// - In CYourWinApp::InitInstance() add :
|
||
// if (CheckMaxAllowedInstances())
|
||
// return FALSE;
|
||
|
||
|
||
// Remark:
|
||
// Shared instance data (through linker) is not used, because when the program is loaded
|
||
// twice, but from a different location, the both have their own (seperate)
|
||
// instance data.
|
||
// See also MSDN "Problem with Shared Data Sections" (PSS ID Number: Q147136)
|
||
// Using the text in the main window to distinguish between different applications
|
||
// is also not waterproof
|
||
// This class uses a method bases on memory mapped files, which is the prefered way
|
||
// of sharing data between processes
|
||
|
||
// Prerequisites (necessary conditions):
|
||
|
||
/////////////////////////////////////////////////////////////////////////////
|
||
|
||
#ifndef __OXINSTANCEMANAGER_H__
|
||
#define __OXINSTANCEMANAGER_H__
|
||
|
||
#if _MSC_VER >= 1000
|
||
#pragma once
|
||
#endif // _MSC_VER >= 1000
|
||
|
||
#include "OXDllExt.h"
|
||
#include "OXMainRes.h"
|
||
|
||
#include <afxmt.h>
|
||
|
||
#include "UTB64Bit.h"
|
||
|
||
#ifndef OX_MAX_NUM_INSTANCES_IN_LIST
|
||
// ... The maximum number of instances that can be tracked
|
||
// Extra instances will be discarded
|
||
// ... The size of an entire CInstanceList object will rounded to the nearest
|
||
// allocation granularity
|
||
#define OX_MAX_NUM_INSTANCES_IN_LIST 1000
|
||
#endif
|
||
|
||
|
||
|
||
|
||
class OX_CLASS_DECL COXInstanceManager : public CObject
|
||
{
|
||
DECLARE_DYNAMIC(COXInstanceManager);
|
||
|
||
// Data members -------------------------------------------------------------
|
||
public:
|
||
static const LPCTSTR m_pszInstanceListMutexPrefix;
|
||
// --- The prefix of the name that will be used to create a mutex
|
||
// to synchronize access to the list of instances
|
||
// The complete name adds the application name
|
||
|
||
static const LPCTSTR m_pszAdditionalDataMutexPrefix;
|
||
// --- The prefix of the name that will be used to create a mutex
|
||
// to synchronize access to the additional data
|
||
// The complete name adds the application name
|
||
|
||
static const LPCTSTR m_pszFileMapPrefix;
|
||
// --- The prefix of the name that will be used to create a file
|
||
// mapping object
|
||
// The complete name adds the application name
|
||
|
||
protected:
|
||
CString m_sApplicationName;
|
||
DWORD m_nInstanceListSize;
|
||
DWORD m_nAdditionalDataSize;
|
||
CMutex m_instanceListMutex;
|
||
CMutex m_additionalDataMutex;
|
||
HANDLE m_hFileMap;
|
||
LPVOID m_pInstanceListView;
|
||
LPVOID m_pAdditionalDataView;
|
||
|
||
struct CInstanceWindow
|
||
{
|
||
DWORD_PTR m_nPID;
|
||
HWND m_hMainWnd;
|
||
};
|
||
|
||
struct CInstanceList
|
||
{
|
||
DWORD m_nMaxAllowedInstances;
|
||
DWORD m_nCurrentNumInstances;
|
||
DWORD m_rgPID[OX_MAX_NUM_INSTANCES_IN_LIST];
|
||
};
|
||
|
||
private:
|
||
|
||
// Member functions ---------------------------------------------------------
|
||
public:
|
||
COXInstanceManager(LPCTSTR pszApplicationName, DWORD nMinAdditionalDataSize = 0);
|
||
// --- In : pszApplicationName : Name identifying this application
|
||
// This must be the same for all instances of a program
|
||
// and must not be empty
|
||
// nAdditionalDataSize : The minimum number of additional bytes that must be shared
|
||
// --- Out :
|
||
// --- Returns :
|
||
// --- Effect : Constructs the object
|
||
|
||
BOOL HasPreviousInstance();
|
||
// --- In :
|
||
// --- Out :
|
||
// --- Returns : Whether there are other instances (apart from this one) running
|
||
// --- Effect :
|
||
|
||
DWORD GetNumberOfInstances();
|
||
// --- In :
|
||
// --- Out :
|
||
// --- Returns : The total number of running instances (this one included)
|
||
// --- Effect :
|
||
|
||
DWORD GetMaxAllowedInstances();
|
||
// --- In :
|
||
// --- Out :
|
||
// --- Returns : The maximum allowable number of running instances (this one included)
|
||
// --- Effect :
|
||
|
||
BOOL SetMaxAllowedInstances(DWORD nMaxAllowedInstances, BOOL bCloseExtra = TRUE);
|
||
// --- In : nMaxAllowedInstances : New maximum allowable number of running instances
|
||
// bCloseExtra : Whether to close extra instances when the max number is exceeded
|
||
// --- Out :
|
||
// --- Returns : Whether it succeeded or not
|
||
// --- Effect : When setting this number to less than the present number of
|
||
// running instances and bCloseExtra is TRUE, some instances will be closed
|
||
|
||
BOOL GetInstanceCollection(CDWordArray& instanceColl);
|
||
// --- In :
|
||
// --- Out : instanceColl : A collection with all the instance IDs
|
||
// --- Returns : Whether it succeeded or not
|
||
// --- Effect :
|
||
|
||
BOOL CheckMaxAllowedInstances(BOOL bActivatePrevious = TRUE);
|
||
// --- In : bActivatePrevious : Whether to activate another instance when the
|
||
// max number has been exceeded
|
||
// --- Out :
|
||
// --- Returns : Whether the maximum number of allowable instances has been exceeded
|
||
// You should close this application when TRUE is returned.
|
||
// --- Effect :
|
||
|
||
static HWND GetMainWindow(DWORD_PTR nPID);
|
||
// --- In : nPID : The instance (process) ID
|
||
// --- Out :
|
||
// --- Returns : The main window of the specified instance when found
|
||
// or NULL otherwise
|
||
// --- Effect : The main window is a top-level, not-owned window of the specified instance
|
||
|
||
static BOOL CloseInstance(DWORD_PTR nPID);
|
||
// --- In : nPID : The instance (process) ID
|
||
// --- Out :
|
||
// --- Returns : Whether it succeeded or not
|
||
// --- Effect : This function tries to terminate to specified instance by
|
||
// closing its mlan window
|
||
// The function will fail if the main window is disabled
|
||
|
||
static DWORD GetCurrentInstanceID();
|
||
// --- In :
|
||
// --- Out :
|
||
// --- Returns : The current instance (process) ID
|
||
// --- Effect :
|
||
|
||
DWORD GetAdditionalDataSize() const;
|
||
// --- In :
|
||
// --- Out :
|
||
// --- Returns : The size in bytes that is avaliable for additioanl sharable data
|
||
// --- Effect : This size may be larger than the size specified in the constructor
|
||
// because space is allocated according to the allocation granularity
|
||
|
||
LPVOID GetAdditionalData();
|
||
// --- In :
|
||
// --- Out :
|
||
// --- Returns : A pointer to the additioanl data if successful, NULL otherwise
|
||
// --- Effect : This pointer is valid until the next call to ReleaseAdditionalData()
|
||
|
||
void ReleaseAdditionalData();
|
||
// --- In :
|
||
// --- Out :
|
||
// --- Returns :
|
||
// --- Effect : Releases the pointer to the additioanl data.
|
||
// A previously pointer returned from GetAdditionalData() is no longer valid
|
||
// This function will also be called when the object is destroyed
|
||
|
||
CMutex& GetAdditionalDataMutex();
|
||
// --- In :
|
||
// --- Out :
|
||
// --- Returns : A mutex that can be used to synchronize access to the additional data
|
||
// --- Effect :
|
||
|
||
#ifdef _DEBUG
|
||
virtual void AssertValid() const;
|
||
// --- In :
|
||
// --- Out :
|
||
// --- Returns :
|
||
// --- Effect : AssertValid performs a validity check on this object
|
||
// by checking its internal state.
|
||
// In the Debug version of the library, AssertValid may assert and
|
||
// thus terminate the program.
|
||
|
||
virtual void Dump(CDumpContext& dc) const;
|
||
// --- In : dc : The diagnostic dump context for dumping, usually afxDump.
|
||
// --- Out :
|
||
// --- Returns :
|
||
// --- Effect : Dumps the contents of the object to a CDumpContext object.
|
||
// It provides diagnostic services for yourself and
|
||
// other users of your class.
|
||
// Note The Dump function does not print a newline character
|
||
// at the end of its output.
|
||
#endif
|
||
|
||
virtual ~COXInstanceManager();
|
||
// --- In :
|
||
// --- Out :
|
||
// --- Returns :
|
||
// --- Effect : Destructor of the object
|
||
|
||
protected:
|
||
BOOL GetInstanceList();
|
||
void ReleaseInstanceList();
|
||
BOOL InitializeInstanceList();
|
||
BOOL AddInstanceToList(DWORD nPID);
|
||
BOOL RemoveInstanceFromList(DWORD nPID);
|
||
static BOOL CALLBACK EnumMainWindows(HWND hWnd, LPARAM lParam);
|
||
|
||
private:
|
||
|
||
};
|
||
|
||
#endif // __OXINSTANCEMANAGER_H__
|
||
// ==========================================================================
|