]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/snglinst.h
Add wxTimer::StartOnce().
[wxWidgets.git] / interface / wx / snglinst.h
index 9093f08a02144803b60f881cff017cf8343d0064..2d68cd0e00875ee28ed235ed8de7d1c7f9f3bc40 100644 (file)
@@ -3,40 +3,40 @@
 // Purpose:     interface of wxSingleInstanceChecker
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class 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
-    wxSingleInstanceChecker::IsAnotherRunning from
-    other processes will return @true.
+    program is running.
+
+    To do it, you should create an object of this class. As long as this object
+    is alive, calls to wxSingleInstanceChecker::IsAnotherRunning from other
+    processes will return @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 wxApp::OnInit. For
-    example:
+    create it either as a global or in wxApp::OnInit.
+    For example:
 
     @code
     bool MyApp::OnInit()
     {
-        const wxString name = wxString::Format("MyApp-%s", wxGetUserId().c_str());
-        m_checker = new wxSingleInstanceChecker(name);
+        m_checker = new wxSingleInstanceChecker;
         if ( m_checker-IsAnotherRunning() )
         {
             wxLogError(_("Another program instance is already running, aborting."));
 
-            delete m_checker; // OnExit() won't be called if we return @false
-            m_checker = @NULL;
+            delete m_checker; // OnExit() won't be called if we return false
+            m_checker = NULL;
 
-            return @false;
+            return false;
         }
 
         ... more initializations ...
 
-        return @true;
+        return true;
     }
 
     int MyApp::OnExit()
     }
     @endcode
 
-    Note using 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.
+    Note that by default wxSingleInstanceChecker::CreateDefault() is used to
+    create the checker meaning that it will be initialized differently for
+    different users and thus will allow different users to run the application
+    concurrently which is usually the required behaviour. However if only a
+    single instance of a program should be running system-wide, you need to
+    call Create() with a custom name which does @em not include wxGetUserId().
 
     This class is implemented for Win32 and Unix platforms (supporting @c fcntl()
     system call, but almost all of modern Unix systems do) only.
 
     @library{wxbase}
-    @category{misc}
+    @category{appmanagement}
 */
 class wxSingleInstanceChecker
 {
 public:
     /**
-        Like Create() but without
-        error checking.
+        Default constructor.
+
+        You may call Create() after using it or directly call
+        IsAnotherRunning() in which case CreateDefault() will be implicitly
+        used.
+    */
+    wxSingleInstanceChecker();
+
+    /**
+        Constructor calling Create().
+
+        This constructor does exactly the same thing as Create() but doesn't
+        allow to check for errors.
     */
     wxSingleInstanceChecker(const wxString& name,
                             const wxString& path = wxEmptyString);
 
     /**
         Destructor frees the associated resources.
-        Note that it is not virtual, this class is not meant to be used polymorphically
+
+        Note that it is not virtual, this class is not meant to be used polymorphically.
     */
     ~wxSingleInstanceChecker();
 
     /**
         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
-        @ref wxsingleinstancechecker() "non default ctor"
-        had been used is an error.
+        non default ctor had been used is an error.
 
         @param name
-            must be given and be as unique as possible. It is used as the
+            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.
-            GetAppName() and wxGetUserId()
-            are commonly used to construct this parameter.
+            wxApp::GetAppName() and wxGetUserId() are commonly used to construct
+            this parameter.
         @param path
-            is optional and is ignored under Win32 and used as the directory to
-            create the lock file in under Unix (default is
-            wxGetHomeDir())
-
-        @return Returns @false if initialization failed, it doesn't mean that
-                 another instance is running - use  IsAnotherRunning()
-                 to check for it.
+            The path is optional and is ignored under Win32 and used as the
+            directory to create the lock file in under Unix
+            (default is wxGetHomeDir()).
+
+        @return
+            Returns @false if initialization failed, it doesn't mean that
+            another instance is running -- use IsAnotherRunning() to check for
+            it.
+
+        @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.
     */
     bool Create(const wxString& name,
                 const wxString& path = wxEmptyString);
 
     /**
-        Returns @true if another copy of this program is already running, @false
-        otherwise.
+        Calls Create() with default name.
+
+        This method simply calls Create() with a string composed of
+        wxApp::GetAppName() and wxGetUserId().
+
+        Because this method uses wxApp::GetAppName(), it may only be called
+        after the global application was constructed.
+
+        @since 2.9.1
+     */
+    bool CreateDefault();
+
+    /**
+        Returns @true if another copy of this program is already running and
+        @false otherwise.
+
+        Notice that if the object was created using the default constructor
+        Create() hadn't been called before this method, it will call
+        CreateDefault() automatically.
     */
     bool IsAnotherRunning() const;
 };