a7af285d1a
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@47777 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
135 lines
4.6 KiB
TeX
135 lines
4.6 KiB
TeX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Name: snglinst.tex
|
|
%% Purpose: wxSingleInstanceChecker documentation
|
|
%% Author: Vadim Zeitlin
|
|
%% Modified by:
|
|
%% Created: 08.06.01
|
|
%% RCS-ID: $Id$
|
|
%% Copyright: (c) 2001 Vadim Zeitlin
|
|
%% License: wxWindows license
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
|
|
\section{\class{wxSingleInstanceChecker}}\label{wxsingleinstancechecker}
|
|
|
|
wxSingleInstanceChecker class allows to check that only a single instance of a
|
|
program is running. To do it, you should create an object of this class. As
|
|
long as this object is alive, calls to
|
|
\helpref{IsAnotherRunning()}{wxsingleinstancecheckerisanotherrunning} from
|
|
other processes will return {\tt true}.
|
|
|
|
As the object should have the life span as big as possible, it makes sense to
|
|
create it either as a global or in \helpref{wxApp::OnInit}{wxapponinit}. For
|
|
example:
|
|
|
|
\begin{verbatim}
|
|
bool MyApp::OnInit()
|
|
{
|
|
const wxString name = wxString::Format("MyApp-%s", wxGetUserId().c_str());
|
|
m_checker = new wxSingleInstanceChecker(name);
|
|
if ( m_checker->IsAnotherRunning() )
|
|
{
|
|
wxLogError(_("Another program instance is already running, aborting."));
|
|
|
|
return false;
|
|
}
|
|
|
|
... more initializations ...
|
|
|
|
return true;
|
|
}
|
|
|
|
int MyApp::OnExit()
|
|
{
|
|
delete m_checker;
|
|
|
|
return 0;
|
|
}
|
|
\end{verbatim}
|
|
|
|
Note using \helpref{wxGetUserId()}{wxgetuserid} to construct the name: this
|
|
allows different user to run the application concurrently which is usually the
|
|
intended goal. If you don't use the user name in the wxSingleInstanceChecker
|
|
name, only one user would be able to run the application at a time.
|
|
|
|
This class is implemented for Win32 and Unix platforms (supporting {\tt fcntl()}
|
|
system call, but almost all of modern Unix systems do) only.
|
|
|
|
\wxheading{Derived from}
|
|
|
|
No base class
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/snglinst.h>
|
|
|
|
\wxheading{Library}
|
|
|
|
\helpref{wxBase}{librarieslist}
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
\membersection{wxSingleInstanceChecker::wxSingleInstanceChecker}\label{wxsingleinstancecheckerctor}
|
|
|
|
\func{}{wxSingleInstanceChecker}{\void}
|
|
|
|
Default ctor, use \helpref{Create()}{wxsingleinstancecheckercreate} after it.
|
|
|
|
\membersection{wxSingleInstanceChecker::wxSingleInstanceChecker}\label{wxsingleinstancecheckerwxsingleinstancechecker}
|
|
|
|
\func{}{wxSingleInstanceChecker}{\param{const wxString\& }{name}, \param{const wxString\& }{path = wxEmptyString}}
|
|
|
|
Like \helpref{Create()}{wxsingleinstancecheckercreate} but without
|
|
error checking.
|
|
|
|
\membersection{wxSingleInstanceChecker::Create}\label{wxsingleinstancecheckercreate}
|
|
|
|
\func{bool}{Create}{\param{const wxString\& }{name}, \param{const wxString\& }{path = wxEmptyString}}
|
|
|
|
Initialize the object if it had been created using the default constructor.
|
|
Note that you can't call Create() more than once, so calling it if the
|
|
\helpref{non default ctor}{wxsingleinstancecheckerwxsingleinstancechecker}
|
|
had been used is an error.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{name}{must be given and be as unique as possible. It is used as the
|
|
mutex name under Win32 and the lock file name under Unix.
|
|
\helpref{GetAppName()}{wxappgetappname} and \helpref{wxGetUserId()}{wxgetuserid}
|
|
are commonly used to construct this parameter.}
|
|
|
|
\docparam{path}{is optional and is ignored under Win32 and used as the directory to
|
|
create the lock file in under Unix (default is
|
|
\helpref{wxGetHomeDir()}{wxgethomedir})}
|
|
|
|
\wxheading{Return value}
|
|
|
|
Returns {\tt false} if initialization failed, it doesn't mean that another
|
|
instance is running - use
|
|
\helpref{IsAnotherRunning()}{wxsingleinstancecheckerisanotherrunning} to check
|
|
for it.
|
|
|
|
\wxheading{Note}
|
|
|
|
One of possible reasons while Create may fail on Unix is that the lock file
|
|
used for checking already exists but was not created by the user.
|
|
Therefore applications shouldn't treat failure of this function as fatal
|
|
condition, because doing so would open them to the possibility of a Denial of
|
|
Service attack. Instead, they should alert the user about the problem and
|
|
offer to continue execution without checking if another instance is running.
|
|
|
|
\membersection{wxSingleInstanceChecker::IsAnotherRunning}\label{wxsingleinstancecheckerisanotherrunning}
|
|
|
|
\constfunc{bool}{IsAnotherRunning}{\void}
|
|
|
|
Returns {\tt true} if another copy of this program is already running, {\tt
|
|
false} otherwise.
|
|
|
|
\membersection{wxSingleInstanceChecker::\destruct{wxSingleInstanceChecker}}\label{wxsingleinstancecheckerdtor}
|
|
|
|
\func{}{\destruct{wxSingleInstanceChecker}}{\void}
|
|
|
|
Destructor frees the associated resources.
|
|
|
|
Note that it is not virtual, this class is not meant to be used polymorphically
|
|
|