aboutsummaryrefslogtreecommitdiff
path: root/singleapplication.h
blob: f123abdb2ef93aa92b889c5c9aa5c3d03819afa1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
// The MIT License (MIT)
//
// 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
// 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:
//
// 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 SINGLE_APPLICATION_H
#define SINGLE_APPLICATION_H

#include <QtCore/QtGlobal>
#include <QtNetwork/QLocalSocket>

#ifndef QAPPLICATION_CLASS
  #define QAPPLICATION_CLASS QCoreApplication
#endif

#include QT_STRINGIFY(QAPPLICATION_CLASS)

class SingleApplicationPrivate;

/**
 * @brief The SingleApplication class handles multipe instances of the same
 * Application
 * @see QCoreApplication
 */
class SingleApplication : public QAPPLICATION_CLASS
{
    Q_OBJECT

    typedef QAPPLICATION_CLASS app_t;

public:
    /**
     * @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
    };
    Q_DECLARE_FLAGS(Options, Mode)

    /**
     * @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
     * if there is already a primary instance.
     * @arg {Mode} mode - Whether for the SingleApplication block to be applied
     * User wide or System wide.
     * @arg {int} timeout - Timeout to wait in miliseconds.
     * @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
     * 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
     * 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
     */
    explicit SingleApplication( int &argc, char *argv[], bool allowSecondary = false, Options options = Mode::User, int timeout = 1000 );
    ~SingleApplication();

    /**
     * @brief Returns if the instance is the primary instance
     * @returns {bool}
     */
    bool isPrimary();

    /**
     * @brief Returns if the instance is a secondary instance
     * @returns {bool}
     */
    bool isSecondary();

    /**
     * @brief Returns a unique identifier for the current instance
     * @returns {qint32}
     */
    quint32 instanceId();

    /**
     * @brief Returns the process ID (PID) of the primary instance
     * @returns {qint64}
     */
    qint64 primaryPid();

    /**
     * @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.
     */
    bool sendMessage( QByteArray message, int timeout = 100 );

Q_SIGNALS:
    void instanceStarted();
    void receivedMessage( quint32 instanceId, QByteArray message );

private:
    SingleApplicationPrivate *d_ptr;
    Q_DECLARE_PRIVATE(SingleApplication)
};

Q_DECLARE_OPERATORS_FOR_FLAGS(SingleApplication::Options)

#endif // SINGLE_APPLICATION_H