commit 8ebfccec4cf68676137f00dcc8e924c1061cedeb Author: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Date: Sun Feb 4 18:45:10 2024 +0000 Deploy to GitHub pages diff --git a/annotated.html b/annotated.html new file mode 100644 index 0000000..ce3a1a2 --- /dev/null +++ b/annotated.html @@ -0,0 +1,129 @@ + + +
+ + + + + + + + + + + + + + + +
+ SingleApplication
+
+ Replacement for QtSingleApplication
+ |
+
CSingleApplication | Handles multiple instances of the same Application |
+ SingleApplication
+
+ Replacement for QtSingleApplication
+ |
+
This is the complete list of members for SingleApplication, including all inherited members.
+
+ SingleApplication
+
+ Replacement for QtSingleApplication
+ |
+
Handles multiple instances of the same Application. + More...
+ +#include <singleapplication.h>
+Public Types | |
enum | Mode { + User = 1 << 0 +, System = 1 << 1 +, SecondaryNotification = 1 << 2 +, ExcludeAppVersion = 1 << 3 +, + ExcludeAppPath = 1 << 4 + + } |
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. More... | |
enum | SendMode { NonBlocking +, BlockUntilPrimaryExit + } |
Mode of operation of sendMessage. More... | |
+Signals | |
+void | instanceStarted () |
Triggered whenever a new instance had been started, except for secondary instances if the Mode::SecondaryNotification flag is not specified. | |
+void | receivedMessage (quint32 instanceId, QByteArray message) |
Triggered whenever there is a message received from a secondary instance. | |
+Public Member Functions | |
SingleApplication (int &argc, char *argv[], bool allowSecondary=false, Options options=Mode::User, int timeout=1000, const QString &userData={}) | |
Intitializes a SingleApplication instance with argc command line arguments in argv. More... | |
bool | isPrimary () const |
Checks if the instance is primary instance. More... | |
bool | isSecondary () const |
Checks if the instance is a secondary instance. More... | |
quint32 | instanceId () const |
Returns a unique identifier for the current instance. More... | |
qint64 | primaryPid () const |
Returns the process ID (PID) of the primary instance. More... | |
QString | primaryUser () const |
Returns the username of the user running the primary instance. More... | |
QString | currentUser () const |
Returns the username of the current user. More... | |
bool | sendMessage (const QByteArray &message, int timeout=100, SendMode sendMode=NonBlocking) |
Sends a message to the primary instance. More... | |
QStringList | userData () const |
Get the set user data. More... | |
Handles multiple instances of the same Application.
+enum SingleApplication::Mode | +
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.
Enumerator | |
---|---|
User | The |
System | The |
SecondaryNotification | Whether to trigger |
ExcludeAppVersion | Excludes the application version from the server name (and memory block) hash + |
ExcludeAppPath | Excludes the application path from the server name (and memory block) hash + |
enum SingleApplication::SendMode | +
+
|
+ +explicit | +
Intitializes a SingleApplication
instance with argc command line arguments in argv.
SingleApplication
block to be applied User wide or System wide. Mode::SecondaryNotification
only works if set on both the primary instance and the secondary instance. SingleApplication
initialisation will be completed in given time, though is a good hint. Usually 4*timeout would be the worst case (fail) scenario. QAPPLICATION_CLASS
constructor for reference QString SingleApplication::currentUser | +( | +) | +const | +
Returns the username of the current user.
+quint32 SingleApplication::instanceId | +( | +) | +const | +
Returns a unique identifier for the current instance.
+bool SingleApplication::isPrimary | +( | +) | +const | +
Checks if the instance is primary instance.
+true
if the instance is primary bool SingleApplication::isSecondary | +( | +) | +const | +
Checks if the instance is a secondary instance.
+true
if the instance is secondary qint64 SingleApplication::primaryPid | +( | +) | +const | +
Returns the process ID (PID) of the primary instance.
+QString SingleApplication::primaryUser | +( | +) | +const | +
Returns the username of the user running the primary instance.
+bool SingleApplication::sendMessage | +( | +const QByteArray & | +message, | +
+ | + | int | +timeout = 100 , |
+
+ | + | SendMode | +sendMode = NonBlocking |
+
+ | ) | ++ |
Sends a message to the primary instance.
+message | data to send |
timeout | timeout for connecting |
sendMode | - Mode of operation |
true
on success QStringList SingleApplication::userData | +( | +) | +const | +
Get the set user data.
+
+ SingleApplication
+
+ Replacement for QtSingleApplication
+ |
+
+ SingleApplication
+
+ Replacement for QtSingleApplication
+ |
+
+ SingleApplication
+
+ Replacement for QtSingleApplication
+ |
+
+ SingleApplication
+
+ Replacement for QtSingleApplication
+ |
+
+ SingleApplication
+
+ Replacement for QtSingleApplication
+ |
+
+ SingleApplication
+
+ Replacement for QtSingleApplication
+ |
+
+ SingleApplication
+
+ Replacement for QtSingleApplication
+ |
+
▼CQAPPLICATION_CLASS | |
CSingleApplication | Handles multiple instances of the same Application |
+ SingleApplication
+
+ Replacement for QtSingleApplication
+ |
+
This is a replacement of the QtSingleApplication for Qt5
and Qt6
.
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.
+You can find the full usage reference and examples here.
+The SingleApplication
class inherits from whatever Q[Core|Gui]Application
class you specify via the QAPPLICATION_CLASS
macro (QCoreApplication
is the default). Further usage is similar to the use of the Q[Core|Gui]Application
classes.
You can use the library as if you use any other QCoreApplication
derived class:
To include the library files I would recommend that you add it as a git submodule to your project. Here is how:
+Qmake:
+Then include the singleapplication.pri
file in your .pro
project file.
CMake:
+Then include the subdirectory in your CMakeLists.txt
project file.
Directly including this repository as a Git submodule, or even just a shallow copy of the source code into new projects might not be ideal when using CMake. Another option is using CMake's FetchContent
module, available since version 3.11
.
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 for connections. Each subsequent instance of your application would check if the shared memory block exists and if it does, it will connect to the QLocalServer to notify the primary instance that a new instance had been started, after which it would terminate with status code 0
. In the Primary Instance SingleApplication
would emit the instanceStarted()
signal upon detecting that a new instance had been started.
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 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.
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 foreground is restricted. See Windows specific implementations for a workaround and an example implementation.
+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 SingleApplication
constructor. The default is false
meaning no Secondary Instances. Here is an example of how you would start a Secondary Instance send a message with the command line arguments to the primary instance and then shut down.
Note: A secondary instance won't cause the emission of the instanceStarted()
signal by default. See SingleApplication::Mode
for more details.*
You can check whether your instance is a primary or secondary with the following methods:
+Note: If your Primary Instance is terminated a newly launched instance will replace the Primary one even if the Secondary flag has been set.*
+There are three examples provided in this repository:
+examples/basic
examples/calculator
examples/sending_arguments
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 for more details.
+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.
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.
+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:
+ SingleApplication
+
+ Replacement for QtSingleApplication
+ |
+
QCryptographicHash::addData()
that will only support QByteArrayView
going further. - Moody LiuwriteAck
on a removed connection. - Nicolas WernerQt 5.9
with min
/max
functions on Windows - Nick Korotyshint
to quint32
and Clang Tidy warnings - Hennadii ChernyshchykinstanceStarted()
to not get emitted when a second instance has been started before the primary has initiated it's QLocalServer
.Fixed an MSVC C4996 warning that suggests using strncpy_s
.
Hennadii Chernyshchyk
+Fixed Clang Tidy warnings
+Hennadii Chernyshchyk
+Improved CMakeLists.txt
Hennadii Chernyshchyk
+Fix a crash when exiting an application on Android and iOS
+Emeric Grange
+Added currentUser() method that returns the user the current instance is running as.
+Leander Schulten
+Fixed code warning for depricated functions in Qt 5.10 related to QTime
and qrand()
.
Hennadii Chernyshchyk
+ Anton Filimonov
+ Jonas Kvinge
Added Build CI tests to verify the library builds successfully on Linux, Windows and MacOS across multiple Qt versions.
+Anton Filimonov
+Fixed compilation warning/error caused by geteuid()
on unix based systems.
Iakov Kirilenko
+Added CMake support
+Hennadii Chernyshchyk
+Use geteuid and getpwuid to get username on Unix, fallback to environment variable.
+Jonas Kvinge
+Bug Fix: sendMessage() might return false even though data was actually written.
+Jonas Kvinge
+SingleApplicationPrivate
constructor.Fix undefined variable error on Windows
+Francis Giraldeau
+Fixed bug where the message sent by the second process was not received correctly when the message is sent immediately following a connection.
+Francis Giraldeau
+qChecksum()
(CRC-16).qWarning
and qCritical
when the library is unable to initialise correctly.instanceId
reading from only one byte in the message deserialization. Cleaned up serialization code using QDataStream
. Changed connection type to use quint8 enum
rather than char
.Renamed SingleAppConnectionType
to ConnectionType
. Added initialization values to all ConnectionType
enum cases.
Jedidiah Buck McCready
+Added SingleApplicationPrivate::primaryPid() as a solution to allow bringing the primary window of an application to the foreground on Windows.
+Eelco van Dam from Peacs BV
+Bug fix - changed QApplication::instance() to QCoreApplication::instance()
+Evgeniy Bazhenov
+Fixed bug in the Calculator example, preventing it's window to be raised on Windows.
+Special thanks to Charles Gunawan.
+Fixed a memory leak in the SingleApplicationPrivate destructor.
+Sergei Moiseev
+Fixed shadow and uninitialised variable warnings.
+Paul Walmsley
+~
) may be returned.Fixed bug on Windows when username containing wide characters causes the library to crash.
+Le Liu
+SingleApplication::Mode::ExcludeAppVersion
SingleApplication::Mode::ExcludeAppPath
Fixes a problem with upper case letters in paths on Windows
+Le Liu
+applicationName
and organizationName
to be set. It instead concatenates all of the following data and computes a SHA256
hash which is used as the key of the QSharedMemory
block and the QLocalServer
. Since at least applicationFilePath
is always present there is no need to explicitly set any of the following prior to initialising SingleApplication
.QCoreApplication::applicationName
QCoreApplication::applicationVersion
QCoreApplication::applicationFilePath
QCoreApplication::organizationName
QCoreApplication::organizationDomain
Mode
flag for this feature exists.instanceNumber()
which represents a unique identifier for each secondary instance started. When called from the primary instance will return 0
.Improved pimpl design and inheritance safety.
+Vladislav Pyatnichenko
+QAPPLICATION_CLASS
macro can now be defined in the file including the Single Application header or with a DEFINES+=
statement in the project file.A race condition can no longer occur when starting two processes nearly simultaneously.
+Fix issue #3
+SingleApplication is now being passed a reference to argc
instead of a copy.
Fix issue #1
+