X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/6bfc18d01649c47eb2157f1333d8c189be83ee4d..97d13342cc2ac77e21c38115cc6ebecac930f92a:/interface/wx/snglinst.h diff --git a/interface/wx/snglinst.h b/interface/wx/snglinst.h index 41e539fde2..4d240abe65 100644 --- a/interface/wx/snglinst.h +++ b/interface/wx/snglinst.h @@ -10,14 +10,15 @@ @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() @@ -47,52 +48,64 @@ } @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 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. 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 ctor, use Create() after it. + */ + wxSingleInstanceChecker(); + + /** + Like Create() but without error checking. */ 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. + @ref wxSingleInstanceChecker() "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. + 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()) + 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. + 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);