diff options
Diffstat (limited to 'singleapplication.h')
| -rw-r--r-- | singleapplication.h | 87 |
1 files changed, 54 insertions, 33 deletions
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: |