diff --git a/.github/workflows/build.yml b/.github/workflows/main.yml similarity index 84% rename from .github/workflows/build.yml rename to .github/workflows/main.yml index dfa770a..d16aa6f 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/main.yml @@ -11,7 +11,25 @@ on: - "**.md" jobs: + doxygen: + name: Doxygen + runs-on: ubuntu-20.04 + steps: + - name: Clone repo + uses: actions/checkout@v2.3.4 + + - name: Install apt packages + run: | + sudo apt-get update + sudo apt-get install doxygen qtbase5-dev + + - name: Generate documentation + run: | + cmake -B build -D DOXYGEN_WARN_AS_ERROR=YES + cmake --build build --target SingleApplicationDocumentation + build: + name: Build strategy: matrix: qt_version: [5.12.6, 5.15.0, 6.0.0, 6.2.0] diff --git a/CHANGELOG.md b/CHANGELOG.md index 65985db..cebb358 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,36 +1,29 @@ -Changelog -========= +# Changelog If by accident I have forgotten to credit someone in the CHANGELOG, email me and I will fix it. -__3.3.4__ ---------- +## 3.3.4 * Fix compilation under Qt 6.2+ and stricter Qt compile settings. - _Christoph Cullmann_ * Provide API for blocking sendMessage. - _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_ @@ -38,55 +31,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()`. @@ -94,8 +79,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. @@ -104,8 +88,7 @@ __3.0.18__ _Anton Filimonov_ -__3.0.17__ ----------- +## 3.0.17 * Fixed compilation warning/error caused by `geteuid()` on unix based systems. @@ -115,40 +98,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. @@ -160,8 +137,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 @@ -172,8 +148,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 @@ -181,23 +156,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 @@ -205,22 +177,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 @@ -230,16 +199,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: @@ -251,8 +218,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. @@ -281,37 +247,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/CMakeLists.txt b/CMakeLists.txt index 780fbad..98d6cda 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -29,6 +29,7 @@ else() endif() find_package(Qt${QT_DEFAULT_MAJOR_VERSION} COMPONENTS ${QT_COMPONENTS} REQUIRED) +find_package(Doxygen) target_link_libraries(${PROJECT_NAME} PUBLIC ${QT_LIBRARIES}) @@ -48,3 +49,14 @@ target_compile_definitions(${PROJECT_NAME} PRIVATE QT_NO_KEYWORDS QT_NO_FOREACH ) + +if(DOXYGEN_FOUND) + set(DOXYGEN_USE_MDFILE_AS_MAINPAGE README.md) + + doxygen_add_docs(${PROJECT_NAME}Documentation + singleapplication.h + CHANGELOG.md + Windows.md + README.md + ) +endif() diff --git a/README.md b/README.md index 716f9a7..ec1f8fc 100644 --- a/README.md +++ b/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,7 @@ 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 ------ +## Usage The `SingleApplication` class inherits from whatever `Q[Core|Gui]Application` class you specify via the `QAPPLICATION_CLASS` macro (`QCoreApplication` is the @@ -57,7 +56,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 +71,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 +91,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 +119,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 +132,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 +143,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 +162,8 @@ 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 `The MIT License (MIT)` with the exception of the Qt calculator examples which is distributed under the BSD license. diff --git a/Windows.md b/Windows.md index 13c52da..84abcca 100644 --- a/Windows.md +++ b/Windows.md @@ -1,15 +1,13 @@ -Windows Specific Implementations -================================ +# Windows Specific Implementations -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. The background process (the primary instance) can bring its windows to the @@ -42,5 +40,3 @@ void App::instanceStarted() { QApplication::setActiveWindow( [window/widget to set to the foreground] ); } ``` - -[AllowSetForegroundWindow]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms632668.aspx diff --git a/singleapplication.h b/singleapplication.h index 5565bb8..954a46e 100644 --- a/singleapplication.h +++ b/singleapplication.h @@ -35,7 +35,7 @@ class SingleApplicationPrivate; /** - * @brief The SingleApplication class handles multiple instances of the same + * @brief Handles multiple instances of the same * Application * @see QCoreApplication */ @@ -47,86 +47,99 @@ 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 Mode of operation of sendMessage. - * @enum */ enum SendMode { NonBlocking, /** Do not wait for the primary instance termination and return immediately */ @@ -134,23 +147,31 @@ public: }; /** - * @brief Sends a message to the primary instance. Returns true on success. - * @param {int} timeout - Timeout for connecting - * @param {SendMode} sendMode - Mode of operation. - * @returns {bool} - * @note sendMessage() will return false if invoked from the primary - * instance. + * @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: