diff --git a/SingleApplication/CHANGELOG.md b/SingleApplication/CHANGELOG.md index 6b5f8ebaf..1044c4c6e 100644 --- a/SingleApplication/CHANGELOG.md +++ b/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. diff --git a/SingleApplication/CMakeLists.txt b/SingleApplication/CMakeLists.txt index 780fbad54..c9771e155 100644 --- a/SingleApplication/CMakeLists.txt +++ b/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() diff --git a/SingleApplication/LICENSE b/SingleApplication/LICENSE index a82e5a68f..2062357fa 100644 --- a/SingleApplication/LICENSE +++ b/SingleApplication/LICENSE @@ -1,6 +1,4 @@ -The MIT License (MIT) - -Copyright (c) Itay Grudev 2015 - 2020 +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 @@ -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. diff --git a/SingleApplication/README.md b/SingleApplication/README.md index 716f9a7e1..ece4de791 100644 --- a/SingleApplication/README.md +++ b/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 ---- - -### 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 ----------- +## 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 -guarantees a race condition will not occur. It also uses a QLocalSocket to +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 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 -------- -This library and it's supporting documentation are released under -`The MIT License (MIT)` with the exception of the Qt calculator examples which -is distributed under the BSD license. +## License + +This library and it's supporting documentation, with the exception of the Qt +calculator examples which is distributed under the BSD license, are released +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. +``` diff --git a/SingleApplication/Windows.md b/SingleApplication/Windows.md index 13c52da0e..97bf72640 100644 --- a/SingleApplication/Windows.md +++ b/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 -details. +restricted, see [AllowSetForegroundWindow()](https://msdn.microsoft.com/en-us/library/windows/desktop/ms632668.aspx) for more 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 -include `Mode::SecondaryNotification`, See `SingleApplication::Mode` for more -details. +`allowSecondary` parameter set to `true` . -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 -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 +You can find [demo code](examples/windows_raise_widget/main.cpp) in the examples directory. diff --git a/SingleApplication/examples/basic/basic.pro b/SingleApplication/examples/basic/basic.pro old mode 100644 new mode 100755 diff --git a/SingleApplication/examples/basic/main.cpp b/SingleApplication/examples/basic/main.cpp old mode 100644 new mode 100755 index b2092c6db..f5539f4f5 --- a/SingleApplication/examples/basic/main.cpp +++ b/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 int main(int argc, char *argv[]) diff --git a/SingleApplication/examples/sending_arguments/main.cpp b/SingleApplication/examples/sending_arguments/main.cpp old mode 100644 new mode 100755 index a9d34dd97..03bf10a4f --- a/SingleApplication/examples/sending_arguments/main.cpp +++ b/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 #include "messagereceiver.h" diff --git a/SingleApplication/examples/sending_arguments/messagereceiver.cpp b/SingleApplication/examples/sending_arguments/messagereceiver.cpp index 0560b0726..686b918e6 100644 --- a/SingleApplication/examples/sending_arguments/messagereceiver.cpp +++ b/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 #include "messagereceiver.h" diff --git a/SingleApplication/examples/sending_arguments/messagereceiver.h b/SingleApplication/examples/sending_arguments/messagereceiver.h index 50a970c8f..9f15db34e 100644 --- a/SingleApplication/examples/sending_arguments/messagereceiver.h +++ b/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 diff --git a/SingleApplication/examples/sending_arguments/sending_arguments.pro b/SingleApplication/examples/sending_arguments/sending_arguments.pro old mode 100644 new mode 100755 diff --git a/SingleApplication/examples/windows_raise_widget/CMakeLists.txt b/SingleApplication/examples/windows_raise_widget/CMakeLists.txt new file mode 100644 index 000000000..d30f2d6a1 --- /dev/null +++ b/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) diff --git a/SingleApplication/examples/windows_raise_widget/main.cpp b/SingleApplication/examples/windows_raise_widget/main.cpp new file mode 100644 index 000000000..f195a9f01 --- /dev/null +++ b/SingleApplication/examples/windows_raise_widget/main.cpp @@ -0,0 +1,59 @@ + +#include + +#include "singleapplication.h" + +#ifdef Q_OS_WINDOWS +#include +#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 +} diff --git a/SingleApplication/examples/windows_raise_widget/windows_raise_widget.pro b/SingleApplication/examples/windows_raise_widget/windows_raise_widget.pro new file mode 100644 index 000000000..adea16dea --- /dev/null +++ b/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 +} diff --git a/SingleApplication/singleapplication.cpp b/SingleApplication/singleapplication.cpp index a91bc6fe2..95c4d183e 100644 --- a/SingleApplication/singleapplication.cpp +++ b/SingleApplication/singleapplication.cpp @@ -1,6 +1,4 @@ -// The MIT License (MIT) -// -// Copyright (c) Itay Grudev 2015 - 2020 +// 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 @@ -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 ); } /** diff --git a/SingleApplication/singleapplication.h b/SingleApplication/singleapplication.h index 91cabf93e..17e3b2524 100644 --- a/SingleApplication/singleapplication.h +++ b/SingleApplication/singleapplication.h @@ -1,6 +1,4 @@ -// The MIT License (MIT) -// -// Copyright (c) Itay Grudev 2015 - 2018 +// 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 @@ -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 { - User = 1 << 0, - System = 1 << 1, - SecondaryNotification = 1 << 2, - ExcludeAppVersion = 1 << 3, - ExcludeAppPath = 1 << 4 + /** 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 {const char *[]} argv - Supplied command line arguments - * @arg {bool} allowSecondary - Whether to start the instance as secondary + * @arg argc - Number of arguments in argv + * @arg argv - Supplied command line arguments + * @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 - * @returns {bool} + * @brief Checks if the instance is primary instance + * @returns `true` if the instance is primary */ bool isPrimary() const; /** - * @brief Returns if the instance is a secondary instance - * @returns {bool} + * @brief Checks if the instance is a secondary instance + * @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. - * @param {int} timeout - Timeout for connecting - * @returns {bool} - * @note sendMessage() will return false if invoked from the primary - * instance. + * @brief Mode of operation of sendMessage. */ - 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: diff --git a/SingleApplication/singleapplication_p.cpp b/SingleApplication/singleapplication_p.cpp index a037f7127..370902214 100644 --- a/SingleApplication/singleapplication_p.cpp +++ b/SingleApplication/singleapplication_p.cpp @@ -1,6 +1,4 @@ -// The MIT License (MIT) -// -// Copyright (c) Itay Grudev 2015 - 2020 +// 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 @@ -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(msecs - time.elapsed()), msg ); + const bool result = writeConfirmedFrame( static_cast(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 ) diff --git a/SingleApplication/singleapplication_p.h b/SingleApplication/singleapplication_p.h index 58507cf3e..6b21516f5 100644 --- a/SingleApplication/singleapplication_p.h +++ b/SingleApplication/singleapplication_p.h @@ -1,6 +1,4 @@ -// The MIT License (MIT) -// -// Copyright (c) Itay Grudev 2015 - 2020 +// 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 @@ -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;