Update SingleApplication to v3.5.1 version

SingleApplication/CHANGELOG.md

@@ -1,35 +1,45 @@
-Changelog
+# Changelog
-=========
 
-If by accident I have forgotten to credit someone in the CHANGELOG, email me and I will fix it.
+## 3.5.1
 
-__3.3.4__
+* Bug Fix: Maximum QNativeIpcKey key size on macOS. - _Jonas Kvinge_
----------
+
+## 3.5.0
+
+* Switch to the new QNativeIpcKey based QSharedMemory constructor with Qt 6.6 and higher. - _Jonas Kvinge_
+
+## 3.4.1
+
+* Improved Windows advapi32 link library dependency. - _Frederik Seiffert_
+
+## 3.4.0
+
+* Provide API for blocking sendMessage. - _Christoph Cullmann_
+* New documentation generation using Doxygen
+* Improved Windows basic widget example
+* Updated Project License
+
+## 3.3.4
 
 * Fix compilation under Qt 6.2+ and stricter Qt compile settings. - _Christoph Cullmann_
 
-__3.3.3__
+## 3.3.3
----------
 
 * Support for Qt 6.3+ - Fixed deprecated `QCryptographicHash::addData()` that will only support `QByteArrayView` going further. - _Moody Liu_
 
-__3.3.2__
+## 3.3.2
----------
 
 * Fixed crash caused by sending a `writeAck` on a removed connection. - _Nicolas Werner_
 
-__3.3.1__
+## 3.3.1
----------
 
 * Added support for _AppImage_ dynamic executable paths. - _Michael Klein_
 
-__3.3.0__
+## 3.3.0
----------
 
 * Fixed message fragmentation issue causing crashes and incorrectly / inconsistently received messages. - _Nils Jeisecke_
 
-__3.2.0__
+## 3.2.0
----------
 
 * Added support for Qt 6  - _Jonas Kvinge_
 * Fixed warning in `Qt 5.9` with `min`/`max` functions on Windows - _Nick Korotysh_
@@ -37,55 +47,47 @@ __3.2.0__
 * Fix build issue with MinGW GCC pedantic mode - _Iakov Kirilenko_
 * Fixed conversion from `int` to `quint32` and Clang Tidy warnings - _Hennadii Chernyshchyk_
 
-__3.1.5__
+## 3.1.5
----------
 
 * Improved library stability in edge cases and very rapid process initialisation
 * Fixed Bug where the shared memory block may have been modified without a lock
 * Fixed Bug causing `instanceStarted()` to not get emitted when a second instance
   has been started before the primary has initiated it's `QLocalServer`.
 
-__3.1.4__
+## 3.1.4
----------
 * Officially supporting and build-testing against Qt 5.15
 * Fixed an MSVC C4996 warning that suggests using `strncpy_s`.
 
     _Hennadii Chernyshchyk_
 
-__3.1.3.1__
+## 3.1.3.1
----------
 * CMake build system improvements
 * Fixed Clang Tidy warnings
 
     _Hennadii Chernyshchyk_
 
-__3.1.3__
+## 3.1.3
----------
 * Improved `CMakeLists.txt`
 
     _Hennadii Chernyshchyk_
 
-__3.1.2__
+## 3.1.2
----------
 
 * Fix a crash when exiting an application on Android and iOS
 
     _Emeric Grange_
 
-__3.1.1a__
+## 3.1.1a
-----------
 
 * Added currentUser() method that returns the user the current instance is running as.
 
     _Leander Schulten_
 
-__3.1.0a__
+## 3.1.0a
-----------
 
 * Added primaryUser() method that returns the user the primary instance is running as.
 
-__3.0.19__
+## 3.0.19
-----------
 
 * Fixed code warning for depricated functions in Qt 5.10 related to `QTime` and `qrand()`.
 
@@ -93,8 +95,7 @@ __3.0.19__
    _Anton Filimonov_  
    _Jonas Kvinge_
 
-__3.0.18__
+## 3.0.18
-----------
 
 * Fallback to standard QApplication class on iOS and Android systems where
   the library is not supported.
@@ -103,8 +104,7 @@ __3.0.18__
 
   _Anton Filimonov_
 
-__3.0.17__
+## 3.0.17
-----------
 
 * Fixed compilation warning/error caused by `geteuid()` on unix based systems.
 
@@ -114,40 +114,34 @@ __3.0.17__
 
    _Hennadii Chernyshchyk_
 
-__3.0.16__
+## 3.0.16
-----------
 
 * Use geteuid and getpwuid to get username on Unix, fallback to environment variable.
 
    _Jonas Kvinge_
 
-__3.0.15__
+## 3.0.15
-----------
 
 * Bug Fix: sendMessage() might return false even though data was actually written.
 
    _Jonas Kvinge_
 
-__3.0.14__
+## 3.0.14
-----------
 
 * Fixed uninitialised variables in the `SingleApplicationPrivate` constructor.
 
-__3.0.13a__
+## 3.0.13a
-----------
 
 * Process socket events asynchronously
 * Fix undefined variable error on Windows
 
    _Francis Giraldeau_
 
-__3.0.12a__
+## 3.0.12a
-----------
 
 * Removed signal handling.
 
-__3.0.11a__
+## 3.0.11a
-----------
 
 * Fixed bug where the message sent by the second process was not received
   correctly when the message is sent immediately following a connection.
@@ -159,8 +153,7 @@ __3.0.11a__
 * Explicit `qWarning` and `qCritical` when the library is unable to initialise
   correctly.
 
-__3.0.10__
+## 3.0.10
-----------
 
 * Removed C style casts and eliminated all clang warnings. Fixed `instanceId`
   reading from only one byte in the message deserialization. Cleaned up
@@ -171,8 +164,7 @@ __3.0.10__
 
     _Jedidiah Buck McCready_
 
-__3.0.9__
+## 3.0.9
----------
 
 *   Added SingleApplicationPrivate::primaryPid() as a solution to allow
     bringing the primary window of an application to the foreground on
@@ -180,23 +172,20 @@ __3.0.9__
 
     _Eelco van Dam from Peacs BV_
 
-__3.0.8__
+## 3.0.8
----------
 
 *   Bug fix - changed QApplication::instance() to QCoreApplication::instance()
 
     _Evgeniy Bazhenov_
 
-__3.0.7a__
+## 3.0.7a
-----------
 
 *   Fixed compilation error with Mingw32 in MXE thanks to Vitaly Tonkacheyev.
 *   Removed QMutex used for thread safe behaviour. The implementation now uses
     QCoreApplication::instance() to get an instance to SingleApplication for
     memory deallocation.
 
-__3.0.6a__
+## 3.0.6a
-----------
 
 *   Reverted GetUserName API usage on Windows. Fixed bug with missing library.
 *   Fixed bug in the Calculator example, preventing it's window to be raised
@@ -204,22 +193,19 @@ __3.0.6a__
 
     Special thanks to Charles Gunawan.
 
-__3.0.5a__
+## 3.0.5a
-----------
 
 *   Fixed a memory leak in the SingleApplicationPrivate destructor.
 
     _Sergei Moiseev_
 
-__3.0.4a__
+## 3.0.4a
-----------
 
 *   Fixed shadow and uninitialised variable warnings.
 
     _Paul Walmsley_
 
-__3.0.3a__
+## 3.0.3a
-----------
 
 *   Removed Microsoft Windows specific code for getting username due to
     multiple problems and compiler differences on Windows platforms. On
@@ -229,16 +215,14 @@ __3.0.3a__
 *   Explicitly getting absolute path of the user's home directory as on Unix
     a relative path (`~`) may be returned.
 
-__3.0.2a__
+## 3.0.2a
-----------
 
 *   Fixed bug on Windows when username containing wide characters causes the
     library to crash.
 
     _Le Liu_
 
-__3.0.1a__
+## 3.0.1a
-----------
 
 *   Allows the application path and version to be excluded from the server name
     hash. The following flags were added for this purpose:
@@ -250,8 +234,7 @@ __3.0.1a__
 
     _Le Liu_
 
-__v3.0a__
+## v3.0a
----------
 
 *   Deprecated secondary instances count.
 *   Added a sendMessage() method to send a message to the primary instance.
@@ -280,37 +263,32 @@ __v3.0a__
     secondary instance started. When called from the primary instance will
     return `0`.
 
-__v2.4__
+## v2.4
---------
 
 *   Stability improvements
 *   Support for secondary instances.
 *   The library now recovers safely after the primary process has crashed
 and the shared memory had not been deleted.
 
-__v2.3__
+## v2.3
---------
 
 *   Improved pimpl design and inheritance safety.
 
     _Vladislav Pyatnichenko_
 
-__v2.2__
+## v2.2
---------
 
 *   The `QAPPLICATION_CLASS` macro can now be defined in the file including the
 Single Application header or with a `DEFINES+=` statement in the project file.
 
-__v2.1__
+## v2.1
---------
 
 *   A race condition can no longer occur when starting two processes nearly
     simultaneously.
 
     Fix issue [#3](https://github.com/itay-grudev/SingleApplication/issues/3)
 
-__v2.0__
+## v2.0
---------
 
 *   SingleApplication is now being passed a reference to `argc` instead of a
     copy.

SingleApplication/CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.12.0)
 
-project(SingleApplication LANGUAGES CXX)
+project(SingleApplication LANGUAGES CXX DESCRIPTION "Replacement for QtSingleApplication")
 
 set(CMAKE_AUTOMOC ON)
 
@@ -30,10 +30,17 @@ endif()
 
 find_package(Qt${QT_DEFAULT_MAJOR_VERSION} COMPONENTS ${QT_COMPONENTS} REQUIRED)
 
+option(SINGLEAPPLICATION_DOCUMENTATION "Generate Doxygen documentation" OFF)
+if(SINGLEAPPLICATION_DOCUMENTATION)
+    find_package(Doxygen)
+endif()
+
 target_link_libraries(${PROJECT_NAME} PUBLIC ${QT_LIBRARIES})
 
 if(WIN32)
-    target_link_libraries(${PROJECT_NAME} PRIVATE advapi32)
+    find_library(advapi32_LIBRARY advapi32 REQUIRED)
+    mark_as_advanced(advapi32_LIBRARY)
+    target_link_libraries(${PROJECT_NAME} PRIVATE ${advapi32_LIBRARY})
 endif()
 
 target_compile_definitions(${PROJECT_NAME} PUBLIC QAPPLICATION_CLASS=${QAPPLICATION_CLASS})
@@ -48,3 +55,31 @@ target_compile_definitions(${PROJECT_NAME} PRIVATE
     QT_NO_KEYWORDS
     QT_NO_FOREACH
 )
+
+if(DOXYGEN_FOUND)
+    # Doxygen theme
+    include(FetchContent)
+    FetchContent_Declare(DoxygenAwesome
+        GIT_REPOSITORY https://github.com/jothepro/doxygen-awesome-css
+        GIT_TAG 4cd62308d825fe0396d2f66ffbab45d0e247724c # 2.0.3
+    )
+    FetchContent_MakeAvailable(DoxygenAwesome)
+    FetchContent_GetProperties(DoxygenAwesome SOURCE_DIR DoxygenAwesome_SOURCE_DIR)
+
+    set(DOXYGEN_USE_MDFILE_AS_MAINPAGE README.md)
+    set(DOXYGEN_GENERATE_TREEVIEW YES)
+    set(DOXYGEN_HTML_HEADER ${DoxygenAwesome_SOURCE_DIR}/doxygen-custom/header.html)
+    set(DOXYGEN_HTML_EXTRA_STYLESHEET ${DoxygenAwesome_SOURCE_DIR}/doxygen-awesome.css)
+    set(DOXYGEN_HTML_EXTRA_FILES
+        ${DoxygenAwesome_SOURCE_DIR}/doxygen-awesome-fragment-copy-button.js
+        ${DoxygenAwesome_SOURCE_DIR}/doxygen-awesome-paragraph-link.js
+        ${DoxygenAwesome_SOURCE_DIR}/doxygen-awesome-darkmode-toggle.js
+    )
+
+    doxygen_add_docs(${PROJECT_NAME}Documentation
+        singleapplication.h
+        CHANGELOG.md
+        Windows.md
+        README.md
+    )
+endif()

SingleApplication/LICENSE

@@ -1,6 +1,4 @@
-The MIT License (MIT)
+Copyright (c) Itay Grudev 2015 - 2023
-
-Copyright (c) Itay Grudev 2015 - 2020
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,6 +7,9 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
+Permission is not granted to use this software or any of the associated files
+as sample data for the purposes of building machine learning models.
+
 The above copyright notice and this permission notice shall be included in
 all copies or substantial portions of the Software.
 

SingleApplication/README.md

@@ -1,5 +1,5 @@
-SingleApplication
+# SingleApplication
-=================
+
 [![CI](https://github.com/itay-grudev/SingleApplication/workflows/CI:%20Build%20Test/badge.svg)](https://github.com/itay-grudev/SingleApplication/actions)
 
 This is a replacement of the QtSingleApplication for `Qt5` and `Qt6`.
@@ -8,8 +8,11 @@ Keeps the Primary Instance of your Application and kills each subsequent
 instances. It can (if enabled) spawn secondary (non-related to the primary)
 instances and can send data to the primary instance from secondary instances.
 
-Usage
+# [Documentation](https://itay-grudev.github.io/SingleApplication/)
------
+
+You can find the full usage reference and examples [here](https://itay-grudev.github.io/SingleApplication/classSingleApplication.html).
+
+## Usage
 
 The `SingleApplication` class inherits from whatever `Q[Core|Gui]Application`
 class you specify via the `QAPPLICATION_CLASS` macro (`QCoreApplication` is the
@@ -57,7 +60,6 @@ add_subdirectory(src/third-party/singleapplication)
 target_link_libraries(${PROJECT_NAME} SingleApplication::SingleApplication)
 ```
 
-
 The library sets up a `QLocalServer` and a `QSharedMemory` block. The first
 instance of your Application is your Primary Instance. It would check if the
 shared memory block exists and if not it will start a `QLocalServer` and listen
@@ -73,10 +75,9 @@ The library uses `stdlib` to terminate the program with the `exit()` function.
 Also don't forget to specify which `QCoreApplication` class your app is using if it
 is not `QCoreApplication` as in examples above.
 
-The `Instance Started` signal
+## Instance started signal
------------------------------
 
-The SingleApplication class implements a `instanceStarted()` signal. You can
+The `SingleApplication` class implements a `instanceStarted()` signal. You can
 bind to that signal to raise your application's window when a new instance had
 been started, for example.
 
@@ -94,13 +95,12 @@ Using `SingleApplication::instance()` is a neat way to get the
 `SingleApplication` instance for binding to it's signals anywhere in your
 program.
 
-__Note:__ On Windows the ability to bring the application windows to the
+_Note:_ On Windows the ability to bring the application windows to the
 foreground is restricted. See [Windows specific implementations](Windows.md)
 for a workaround and an example implementation.
 
 
-Secondary Instances
+## Secondary Instances
--------------------
 
 If you want to be able to launch additional Secondary Instances (not related to
 your Primary Instance) you have to enable that with the third parameter of the
@@ -123,7 +123,7 @@ int main(int argc, char *argv[])
 }
 ```
 
-*__Note:__ A secondary instance won't cause the emission of the
+_Note:_ A secondary instance won't cause the emission of the
 `instanceStarted()` signal by default. See `SingleApplication::Mode` for more
 details.*
 
@@ -136,11 +136,10 @@ app.isPrimary();
 app.isSecondary();
 ```
 
-*__Note:__ If your Primary Instance is terminated a newly launched instance
+_Note:_ If your Primary Instance is terminated a newly launched instance
 will replace the Primary one even if the Secondary flag has been set.*
 
-Examples
+## Examples
---------
 
 There are three examples provided in this repository:
 
@@ -148,149 +147,18 @@ There are three examples provided in this repository:
 * An example of a graphical application raising it's parent window [`examples/calculator`](https://github.com/itay-grudev/SingleApplication/tree/master/examples/calculator)
 * A console application sending the primary instance it's command line parameters [`examples/sending_arguments`](https://github.com/itay-grudev/SingleApplication/tree/master/examples/sending_arguments)
 
-API
+## Versioning
----
-
-### Members
-
-```cpp
-SingleApplication::SingleApplication( int &argc, char *argv[], bool allowSecondary = false, Options options = Mode::User, int timeout = 100, QString userData = QString() )
-```
-
-Depending on whether `allowSecondary` is set, this constructor may terminate
-your app if there is already a primary instance running. Additional `Options`
-can be specified to set whether the SingleApplication block should work
-user-wide or system-wide. Additionally the `Mode::SecondaryNotification` may be
-used to notify the primary instance whenever a secondary instance had been
-started (disabled by default). `timeout` specifies the maximum time in
-milliseconds to wait for blocking operations. Setting `userData` provides additional data that will isolate this instance from other instances that do not have the same (or any) user data set.
-
-*__Note:__ `argc` and `argv` may be changed as Qt removes arguments that it
-recognizes.*
-
-*__Note:__ `Mode::SecondaryNotification` only works if set on both the primary
-and the secondary instance.*
-
-*__Note:__ Operating system can restrict the shared memory blocks to the same
-user, in which case the User/System modes will have no effect and the block will
-be user wide.*
-
----
-
-```cpp
-bool SingleApplication::sendMessage( QByteArray message, int timeout = 100 )
-```
-
-Sends `message` to the Primary Instance. Uses `timeout` as a the maximum timeout
-in milliseconds for blocking functions. Returns `true` if the message has been sent
-successfully. If the message can't be sent or the function timeouts - returns `false`.
-
----
-
-```cpp
-bool SingleApplication::isPrimary()
-```
-
-Returns if the instance is the primary instance.
-
----
-
-```cpp
-bool SingleApplication::isSecondary()
-```
-Returns if the instance is a secondary instance.
-
----
-
-```cpp
-quint32 SingleApplication::instanceId()
-```
-
-Returns a unique identifier for the current instance.
-
----
-
-```cpp
-qint64 SingleApplication::primaryPid()
-```
-
-Returns the process ID (PID) of the primary instance.
-
----
-
-```cpp
-QString SingleApplication::primaryUser()
-```
-
-Returns the username the primary instance is running as.
-
----
-
-```cpp
-QString SingleApplication::currentUser()
-```
-
-Returns the username the current instance is running as.
-
-### Signals
-
-```cpp
-void SingleApplication::instanceStarted()
-```
-
-Triggered whenever a new instance had been started, except for secondary
-instances if the `Mode::SecondaryNotification` flag is not specified.
-
----
-
-```cpp
-void SingleApplication::receivedMessage( quint32 instanceId, QByteArray message )
-```
-
-Triggered whenever there is a message received from a secondary instance.
-
----
-
-### Flags
-
-```cpp
-enum SingleApplication::Mode
-```
-
-*   `Mode::User` - The SingleApplication block should apply user wide. This adds
-    user specific data to the key used for the shared memory and server name.
-    This is the default functionality.
-*   `Mode::System` – The SingleApplication block applies system-wide.
-*   `Mode::SecondaryNotification` – Whether to trigger `instanceStarted()` even
-    whenever secondary instances are started.
-*   `Mode::ExcludeAppPath` – Excludes the application path from the server name
-    (and memory block) hash.
-*   `Mode::ExcludeAppVersion` – Excludes the application version from the server
-    name (and memory block) hash.
-
-*__Note:__ `Mode::SecondaryNotification` only works if set on both the primary
-and the secondary instance.*
-
-*__Note:__ Operating system can restrict the shared memory blocks to the same
-user, in which case the User/System modes will have no effect and the block will
-be user wide.*
-
----
-
-Versioning
-----------
 
 Each major version introduces either very significant changes or is not
 backwards compatible with the previous version. Minor versions only add
 additional features, bug fixes or performance improvements and are backwards
-compatible with the previous release. See [`CHANGELOG.md`](CHANGELOG.md) for
+compatible with the previous release. See [CHANGELOG.md](CHANGELOG.md) for
 more details.
 
-Implementation
+## Implementation
---------------
 
-The library is implemented with a QSharedMemory block which is thread safe and
+The library is implemented with a `QSharedMemory` block which is thread safe and
-guarantees a race condition will not occur. It also uses a QLocalSocket to
+guarantees a race condition will not occur. It also uses a `QLocalSocket` to
 notify the main process that a new instance had been spawned and thus invoke the
 `instanceStarted()` signal and for messaging the primary instance.
 
@@ -298,8 +166,13 @@ Additionally the library can recover from being forcefully killed on *nix
 systems and will reset the memory block given that there are no other
 instances running.
 
-License
+## License
--------
+
-This library and it's supporting documentation are released under
+This library and it's supporting documentation, with the exception of the Qt 
-`The MIT License (MIT)` with the exception of the Qt calculator examples which
+calculator examples which is distributed under the BSD license, are released
-is distributed under the BSD license.
+under the terms of `The MIT License (MIT)` with an extra condition, that:
+
+```txt
+Permission is not granted to use this software or any of the associated files
+as sample data for the purposes of building machine learning models.
+```

SingleApplication/Windows.md

@@ -1,46 +1,21 @@
-Windows Specific Implementations
+# Windows Specifics
-================================
 
-Setting the foreground window
+## Setting the foreground window
------------------------------
 
 In the `instanceStarted()` example in the `README` we demonstrated how an
 application can bring it's primary instance window whenever a second copy
 of the application is started.
 
 On Windows the ability to bring the application windows to the foreground is
-restricted, see [`AllowSetForegroundWindow()`][AllowSetForegroundWindow] for more
+restricted, see [AllowSetForegroundWindow()](https://msdn.microsoft.com/en-us/library/windows/desktop/ms632668.aspx) for more details.
-details.
 
 The background process (the primary instance) can bring its windows to the
 foreground if it is allowed by the current foreground process (the secondary
 instance). To bypass this `SingleApplication` must be initialized with the
-`allowSecondary` parameter set to `true` and the `options` parameter must
+`allowSecondary` parameter set to `true` .
-include `Mode::SecondaryNotification`, See `SingleApplication::Mode` for more
-details.
 
-Here is an example:
+If the widget is minimized to Windows task bar, `QWidget::raise()` or
+`QWidget::show()` can not bring it to the front, you have to use Windows API
+`ShowWindow()` .
 
-```cpp
+You can find [demo code](examples/windows_raise_widget/main.cpp) in the examples directory.
-if( app.isSecondary() ) {
-    // This API requires LIBS += User32.lib to be added to the project
-    AllowSetForegroundWindow( DWORD( app.primaryPid() ) );
-}
-
-if( app.isPrimary() ) {
-    QObject::connect(
-        &app,
-        &SingleApplication::instanceStarted,
-        this,
-        &App::instanceStarted
-    );
-}
-```
-
-```cpp
-void App::instanceStarted() {
-    QApplication::setActiveWindow( [window/widget to set to the foreground] );
-}
-```
-
-[AllowSetForegroundWindow]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms632668.aspx

SingleApplication/examples/basic/main.cpp

@@ -1,3 +1,26 @@
+// Copyright (c) Itay Grudev 2015 - 2023
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// Permission is not granted to use this software or any of the associated files
+// as sample data for the purposes of building machine learning models.
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
 #include <singleapplication.h>
 
 int main(int argc, char *argv[])

SingleApplication/examples/sending_arguments/main.cpp

@@ -1,3 +1,26 @@
+// Copyright (c) Itay Grudev 2015 - 2023
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// Permission is not granted to use this software or any of the associated files
+// as sample data for the purposes of building machine learning models.
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
 #include <singleapplication.h>
 #include "messagereceiver.h"
 

SingleApplication/examples/sending_arguments/messagereceiver.cpp

@@ -1,3 +1,26 @@
+// Copyright (c) Itay Grudev 2015 - 2023
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// Permission is not granted to use this software or any of the associated files
+// as sample data for the purposes of building machine learning models.
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
 #include <QDebug>
 #include "messagereceiver.h"
 

SingleApplication/examples/sending_arguments/messagereceiver.h

@@ -1,3 +1,26 @@
+// Copyright (c) Itay Grudev 2015 - 2023
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// Permission is not granted to use this software or any of the associated files
+// as sample data for the purposes of building machine learning models.
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
 #ifndef MESSAGERECEIVER_H
 #define MESSAGERECEIVER_H
 

SingleApplication/examples/windows_raise_widget/CMakeLists.txt

@@ -0,0 +1,16 @@
+cmake_minimum_required(VERSION 3.7.0)
+
+project(windows_raise_widget LANGUAGES CXX)
+
+set(CMAKE_AUTOMOC ON)
+set(CMAKE_WIN32_EXECUTABLE TRUE)
+
+# SingleApplication base class
+set(QAPPLICATION_CLASS QApplication)
+add_subdirectory(../.. SingleApplication)
+
+find_package(Qt${QT_DEFAULT_MAJOR_VERSION} COMPONENTS Core Widgets REQUIRED)
+
+add_executable(${PROJECT_NAME} main.cpp)
+
+target_link_libraries(${PROJECT_NAME} SingleApplication::SingleApplication)

SingleApplication/examples/windows_raise_widget/main.cpp

@@ -0,0 +1,59 @@
+
+#include <QWidget>
+
+#include "singleapplication.h"
+
+#ifdef Q_OS_WINDOWS
+#include <Windows.h>
+#endif
+
+void raiseWidget(QWidget* widget);
+
+int main(int argc, char *argv[]) {
+
+#ifdef Q_OS_WINDOWS
+    SingleApplication app(argc, argv, true);
+
+    if (app.isSecondary()) {
+
+        AllowSetForegroundWindow( DWORD( app.primaryPid() ) );
+
+        app.sendMessage("RAISE_WIDGET");
+
+        return 0;
+    }
+#else
+    SingleApplication app(argc, argv);
+#endif
+
+    QWidget* widget = new QWidget;
+
+#ifdef Q_OS_WINDOWS
+    QObject::connect(&app, &SingleApplication::receivedMessage,
+                     widget, [widget] () { raiseWidget(widget); } );
+#else
+    QObject::connect(&app, &SingleApplication::instanceStarted,
+                     widget, [widget] () { raiseWidget(widget); } );
+#endif
+
+    widget->show();
+
+    return app.exec();
+}
+
+void raiseWidget(QWidget* widget) {
+#ifdef Q_OS_WINDOWS
+    HWND hwnd = (HWND)widget->winId();
+
+    // check if widget is minimized to Windows task bar
+    if (::IsIconic(hwnd)) {
+        ::ShowWindow(hwnd, SW_RESTORE);
+    }
+
+    ::SetForegroundWindow(hwnd);
+#else
+    widget->show();
+    widget->raise();
+    widget->activateWindow();
+#endif
+}

SingleApplication/examples/windows_raise_widget/windows_raise_widget.pro

@@ -0,0 +1,10 @@
+# Single Application implementation
+include(../../singleapplication.pri)
+DEFINES += QAPPLICATION_CLASS=QApplication
+
+QT += widgets
+SOURCES += main.cpp
+
+win32{
+  LIBS += User32.lib
+}

SingleApplication/singleapplication.cpp

@@ -1,6 +1,4 @@
-// The MIT License (MIT)
+// Copyright (c) Itay Grudev 2015 - 2023
-//
-// Copyright (c) Itay Grudev 2015 - 2020
 //
 // Permission is hereby granted, free of charge, to any person obtaining a copy
 // of this software and associated documentation files (the "Software"), to deal
@@ -9,6 +7,9 @@
 // copies of the Software, and to permit persons to whom the Software is
 // furnished to do so, subject to the following conditions:
 //
+// Permission is not granted to use this software or any of the associated files
+// as sample data for the purposes of building machine learning models.
+//
 // The above copyright notice and this permission notice shall be included in
 // all copies or substantial portions of the Software.
 //
@@ -66,12 +67,20 @@ SingleApplication::SingleApplication( int &argc, char *argv[], bool allowSeconda
 #ifdef Q_OS_UNIX
     // By explicitly attaching it and then deleting it we make sure that the
     // memory is deleted even after the process has crashed on Unix.
+#if QT_VERSION >= QT_VERSION_CHECK(6, 6, 0)
+    d->memory = new QSharedMemory( QNativeIpcKey( d->blockServerName ) );
+#else
     d->memory = new QSharedMemory( d->blockServerName );
+#endif
     d->memory->attach();
     delete d->memory;
 #endif
     // Guarantee thread safe behaviour with a shared memory block.
+#if QT_VERSION >= QT_VERSION_CHECK(6, 6, 0)
+    d->memory = new QSharedMemory( QNativeIpcKey( d->blockServerName ) );
+#else
     d->memory = new QSharedMemory( d->blockServerName );
+#endif
 
     // Create a shared memory block
     if( d->memory->create( sizeof( InstancesInfo ) )){
@@ -235,9 +244,10 @@ QString SingleApplication::currentUser() const
  * Sends message to the Primary Instance.
  * @param message The message to send.
  * @param timeout the maximum timeout in milliseconds for blocking functions.
- * @return true if the message was sent successfully, false otherwise.
+ * @param sendMode mode of operation
+ * @return true if the message was sent successfuly, false otherwise.
  */
-bool SingleApplication::sendMessage( const QByteArray &message, int timeout )
+bool SingleApplication::sendMessage( const QByteArray &message, int timeout, SendMode sendMode )
 {
     Q_D( SingleApplication );
 
@@ -248,7 +258,7 @@ bool SingleApplication::sendMessage( const QByteArray &message, int timeout )
     if( ! d->connectToPrimary( timeout,  SingleApplicationPrivate::Reconnect ) )
       return false;
 
-    return d->writeConfirmedMessage( timeout, message );
+    return d->writeConfirmedMessage( timeout, message, sendMode );
 }
 
 /**

SingleApplication/singleapplication.h

@@ -1,6 +1,4 @@
-// The MIT License (MIT)
+// Copyright (c) Itay Grudev 2015 - 2023
-//
-// Copyright (c) Itay Grudev 2015 - 2018
 //
 // Permission is hereby granted, free of charge, to any person obtaining a copy
 // of this software and associated documentation files (the "Software"), to deal
@@ -9,6 +7,9 @@
 // copies of the Software, and to permit persons to whom the Software is
 // furnished to do so, subject to the following conditions:
 //
+// Permission is not granted to use this software or any of the associated files
+// as sample data for the purposes of building machine learning models.
+//
 // The above copyright notice and this permission notice shall be included in
 // all copies or substantial portions of the Software.
 //
@@ -35,7 +36,7 @@
 class SingleApplicationPrivate;
 
 /**
- * @brief The SingleApplication class handles multiple instances of the same
+ * @brief Handles multiple instances of the same
  * Application
  * @see QCoreApplication
  */
@@ -47,100 +48,131 @@ class SingleApplication : public QAPPLICATION_CLASS
 
 public:
     /**
-     * @brief Mode of operation of SingleApplication.
+     * @brief Mode of operation of `SingleApplication`.
      * Whether the block should be user-wide or system-wide and whether the
      * primary instance should be notified when a secondary instance had been
      * started.
      * @note Operating system can restrict the shared memory blocks to the same
      * user, in which case the User/System modes will have no effect and the
      * block will be user wide.
-     * @enum
      */
     enum Mode {
+        /** The `SingleApplication` block should apply user wide
+         * (this adds user specific data to the key used for the shared memory and server name)
+         * */
         User = 1 << 0,
+        /**
+         * The `SingleApplication` block applies system-wide.
+         */
         System = 1 << 1,
+        /**
+         * Whether to trigger `instanceStarted()` even whenever secondary instances are started
+         */
         SecondaryNotification = 1 << 2,
+        /**
+         * Excludes the application version from the server name (and memory block) hash
+         */
         ExcludeAppVersion = 1 << 3,
+        /**
+         * Excludes the application path from the server name (and memory block) hash
+         */
         ExcludeAppPath = 1 << 4
     };
     Q_DECLARE_FLAGS(Options, Mode)
 
     /**
-     * @brief Intitializes a SingleApplication instance with argc command line
+     * @brief Intitializes a `SingleApplication` instance with argc command line
      * arguments in argv
-     * @arg {int &} argc - Number of arguments in argv
+     * @arg argc - Number of arguments in argv
-     * @arg {const char *[]} argv - Supplied command line arguments
+     * @arg argv - Supplied command line arguments
-     * @arg {bool} allowSecondary - Whether to start the instance as secondary
+     * @arg allowSecondary - Whether to start the instance as secondary
      * if there is already a primary instance.
-     * @arg {Mode} mode - Whether for the SingleApplication block to be applied
+     * @arg mode - Whether for the `SingleApplication` block to be applied
      * User wide or System wide.
-     * @arg {int} timeout - Timeout to wait in milliseconds.
+     * @arg timeout - Timeout to wait in milliseconds.
      * @note argc and argv may be changed as Qt removes arguments that it
      * recognizes
-     * @note Mode::SecondaryNotification only works if set on both the primary
+     * @note `Mode::SecondaryNotification` only works if set on both the primary
      * instance and the secondary instance.
      * @note The timeout is just a hint for the maximum time of blocking
-     * operations. It does not guarantee that the SingleApplication
+     * operations. It does not guarantee that the `SingleApplication`
      * initialisation will be completed in given time, though is a good hint.
      * Usually 4*timeout would be the worst case (fail) scenario.
-     * @see See the corresponding QAPPLICATION_CLASS constructor for reference
+     * @see See the corresponding `QAPPLICATION_CLASS` constructor for reference
      */
     explicit SingleApplication( int &argc, char *argv[], bool allowSecondary = false, Options options = Mode::User, int timeout = 1000, const QString &userData = {} );
     ~SingleApplication() override;
 
     /**
-     * @brief Returns if the instance is the primary instance
+     * @brief Checks if the instance is primary instance
-     * @returns {bool}
+     * @returns `true` if the instance is primary
      */
     bool isPrimary() const;
 
     /**
-     * @brief Returns if the instance is a secondary instance
+     * @brief Checks if the instance is a secondary instance
-     * @returns {bool}
+     * @returns `true` if the instance is secondary
      */
     bool isSecondary() const;
 
     /**
      * @brief Returns a unique identifier for the current instance
-     * @returns {qint32}
+     * @returns instance id
      */
     quint32 instanceId() const;
 
     /**
      * @brief Returns the process ID (PID) of the primary instance
-     * @returns {qint64}
+     * @returns pid
      */
     qint64 primaryPid() const;
 
     /**
      * @brief Returns the username of the user running the primary instance
-     * @returns {QString}
+     * @returns user name
      */
     QString primaryUser() const;
 
     /**
      * @brief Returns the username of the current user
-     * @returns {QString}
+     * @returns user name
      */
     QString currentUser() const;
 
     /**
-     * @brief Sends a message to the primary instance. Returns true on success.
+     * @brief Mode of operation of sendMessage.
-     * @param {int} timeout - Timeout for connecting
-     * @returns {bool}
-     * @note sendMessage() will return false if invoked from the primary
-     * instance.
      */
-    bool sendMessage( const QByteArray &message, int timeout = 100 );
+    enum SendMode {
+        NonBlocking,  /** Do not wait for the primary instance termination and return immediately */
+        BlockUntilPrimaryExit,  /** Wait until the primary instance is terminated */
+    };
+
+    /**
+     * @brief Sends a message to the primary instance
+     * @param message data to send
+     * @param timeout timeout for connecting
+     * @param sendMode - Mode of operation
+     * @returns `true` on success
+     * @note sendMessage() will return false if invoked from the primary instance
+     */
+    bool sendMessage( const QByteArray &message, int timeout = 100, SendMode sendMode = NonBlocking );
 
     /**
      * @brief Get the set user data.
-     * @returns {QStringList}
+     * @returns user data
      */
     QStringList userData() const;
 
 Q_SIGNALS:
+    /**
+     * @brief Triggered whenever a new instance had been started,
+     * except for secondary instances if the `Mode::SecondaryNotification` flag is not specified
+     */
     void instanceStarted();
+
+    /**
+     * @brief Triggered whenever there is a message received from a secondary instance
+     */
     void receivedMessage( quint32 instanceId, QByteArray message );
 
 private:

SingleApplication/singleapplication_p.cpp

@@ -1,6 +1,4 @@
-// The MIT License (MIT)
+// Copyright (c) Itay Grudev 2015 - 2023
-//
-// Copyright (c) Itay Grudev 2015 - 2020
 //
 // Permission is hereby granted, free of charge, to any person obtaining a copy
 // of this software and associated documentation files (the "Software"), to deal
@@ -9,6 +7,9 @@
 // copies of the Software, and to permit persons to whom the Software is
 // furnished to do so, subject to the following conditions:
 //
+// Permission is not granted to use this software or any of the associated files
+// as sample data for the purposes of building machine learning models.
+//
 // The above copyright notice and this permission notice shall be included in
 // all copies or substantial portions of the Software.
 //
@@ -130,7 +131,12 @@ QString SingleApplicationPrivate::getUsername()
 
 void SingleApplicationPrivate::genBlockServerName()
 {
+#ifdef Q_OS_MACOS
+    // Maximum key size on macOS is PSHMNAMLEN (31).
+    QCryptographicHash appData( QCryptographicHash::Md5 );
+#else
     QCryptographicHash appData( QCryptographicHash::Sha256 );
+#endif
 #if QT_VERSION < QT_VERSION_CHECK(6, 3, 0)
     appData.addData( "SingleApplication", 17 );
 #else
@@ -283,7 +289,7 @@ void SingleApplicationPrivate::writeAck( QLocalSocket *sock ) {
     sock->putChar('\n');
 }
 
-bool SingleApplicationPrivate::writeConfirmedMessage (int msecs, const QByteArray &msg)
+bool SingleApplicationPrivate::writeConfirmedMessage (int msecs, const QByteArray &msg, SingleApplication::SendMode sendMode)
 {
     QElapsedTimer time;
     time.start();
@@ -301,7 +307,13 @@ bool SingleApplicationPrivate::writeConfirmedMessage (int msecs, const QByteArra
         return false;
 
     // Frame 2: The message
-    return writeConfirmedFrame( static_cast<int>(msecs - time.elapsed()), msg );
+    const bool result = writeConfirmedFrame( static_cast<int>(msecs - time.elapsed()), msg );
+
+    // Block if needed
+    if (socket && sendMode == SingleApplication::BlockUntilPrimaryExit)
+        socket->waitForDisconnected(-1);
+
+    return result;
 }
 
 bool SingleApplicationPrivate::writeConfirmedFrame( int msecs, const QByteArray &msg )

SingleApplication/singleapplication_p.h

@@ -1,6 +1,4 @@
-// The MIT License (MIT)
+// Copyright (c) Itay Grudev 2015 - 2023
-//
-// Copyright (c) Itay Grudev 2015 - 2020
 //
 // Permission is hereby granted, free of charge, to any person obtaining a copy
 // of this software and associated documentation files (the "Software"), to deal
@@ -9,6 +7,9 @@
 // copies of the Software, and to permit persons to whom the Software is
 // furnished to do so, subject to the following conditions:
 //
+// Permission is not granted to use this software or any of the associated files
+// as sample data for the purposes of building machine learning models.
+//
 // The above copyright notice and this permission notice shall be included in
 // all copies or substantial portions of the Software.
 //
@@ -85,7 +86,7 @@ public:
     void readInitMessageBody(QLocalSocket *socket);
     void writeAck(QLocalSocket *sock);
     bool writeConfirmedFrame(int msecs, const QByteArray &msg);
-    bool writeConfirmedMessage(int msecs, const QByteArray &msg);
+    bool writeConfirmedMessage(int msecs, const QByteArray &msg, SingleApplication::SendMode sendMode = SingleApplication::NonBlocking);
     static void randomSleep();
     void addAppData(const QString &data);
     QStringList appData() const;