added and documented wxKeyEvent::GetUnicodeKey(); made it work for MSW; added test...

[wxWidgets.git] / docs / latex / wx / snglinst.tex

diff --git a/docs/latex/wx/snglinst.tex b/docs/latex/wx/snglinst.tex
index 5064291a3d55ad0059d0a2b8846d6891a89e3710..54517eaea3afa1d8a16266e8437b5c3279b50346 100644 (file)
--- a/docs/latex/wx/snglinst.tex
+++ b/docs/latex/wx/snglinst.tex
@@ -6,7 +6,7 @@
 %% Created:     08.06.01
 %% RCS-ID:      $Id$
 %% Copyright:   (c) 2001 Vadim Zeitlin
-%% License:     wxWindows license
+%% License:     wxWidgets license
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{\class{wxSingleInstanceChecker}}\label{wxsingleinstancechecker}
@@ -15,7 +15,7 @@ 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}.
+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
@@ -24,17 +24,18 @@ example:
 \begin{verbatim}
 bool MyApp::OnInit()
 {
-    m_checker = new wxSingleInstanceChecker(GetAppName());
+    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;
+        return false;
     }
 
     ... more initializations ...
 
-    return TRUE;
+    return true;
 }
 
 int MyApp::OnExit()
@@ -45,8 +46,13 @@ int MyApp::OnExit()
 }
 \end{verbatim}
 
-This class is implemented for Win32 and Unix platforms supporting {\tt fcntl()}
-system call only.
+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}
 
@@ -84,7 +90,8 @@ had been used is an error.
 
 \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} may be a good value for this parameter}
+\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 
@@ -92,17 +99,26 @@ create the lock file in under Unix (default is
 
 \wxheading{Return value}
 
-Returns {\tt FALSE} if initialization failed, it doesn't mean that another
+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.
+Returns {\tt true} if another copy of this program is already running, {\tt
+false} otherwise.
 
 \membersection{wxSingleInstanceChecker::\destruct{wxSingleInstanceChecker}}\label{wxsingleinstancecheckerdtor}