SingleInstance Class Reference

The SingleInstance class handles multiple instances. More...

#include <SingleInstance.h>

Inheritance diagram for SingleInstance:

Collaboration diagram for SingleInstance:

Public Types
enum	Mode {   User = 1 << 0 , System = 1 << 1 , SecondaryNotification = 1 << 2 , ExcludeAppVersion = 1 << 3 ,   ExcludeAppPath = 1 << 4 }
	Mode of operation of SingleInstance. 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...

Signals
void	instanceStarted ()
void	receivedMessage (quint32 instanceId, QByteArray message)

Public Member Functions
	SingleInstance (QObject *parent=nullptr)
	Default constructor.
	SingleInstance (bool allowSecondary, Options options=Mode::User, int timeout=1000, const QString &userData={}, QObject *parent=nullptr)
	Initializing constructor.
	~SingleInstance () override
	Destructor.
void	initialize (bool allowSecondary=false, Options options=Mode::User, int timeout=1000, const QString &userData={})
	Initializes this instance.
bool	isPrimary () const
	Gets if the instance is the primary instance.
bool	isSecondary () const
	Gets if the instance is a secondary instance.
quint32	instanceId () const
	Gets a unique identifier for the current instance.
qint64	primaryPid () const
	Gets the process ID (PID) of the primary instance.
QString	primaryUser () const
	Gets the username of the user running the primary instance.
QString	currentUser () const
	Gets the username of the current user.
bool	sendMessage (const QByteArray &message, int timeout=100)
	Sends a message to the primary instance. Returns true on success.
QStringList	userData () const
	Get the set user data.

Detailed Description

The SingleInstance class handles multiple instances.

Member Enumeration Documentation

Mode

enum SingleInstance::Mode

Mode of operation of SingleInstance. 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.

Enumerator
User
System
SecondaryNotification
ExcludeAppVersion
ExcludeAppPath

Constructor & Destructor Documentation

SingleInstance() [1/2]

SingleInstance::SingleInstance ( QObject * parent = nullptr )

explicit

Default constructor.

SingleInstance() [2/2]

SingleInstance::SingleInstance ( bool allowSecondary, Options options = Mode::User, int timeout = 1000, const QString & userData = {}, QObject * parent = nullptr )

explicit

Initializing constructor.

See also

initialize() for more.

~SingleInstance()

SingleInstance::~SingleInstance ( )

override

Destructor.

Member Function Documentation

currentUser()

QString SingleInstance::currentUser ( ) const

nodiscard

Gets the username of the current user.

initialize()

void SingleInstance::initialize	(	bool	allowSecondary = false,
		Options	options = Mode::User,
		int	timeout = 1000,
		const QString &	userData = {} )

Initializes this instance.

Parameters

allowSecondary	Whether to start the instance as secondary if there is already a primary instance.
options	Whether for the SingleInstance block to be applied User wide or System wide.
timeout	Timeout to wait in milliseconds.
userData

Note

argc and argv may be changed as Qt removes arguments that it recognizes

Mode::SecondaryNotification only works if set on both the primary instance and the secondary instance.

The timeout is just a hint for the maximum time of blocking operations. It does not guarantee that the SingleInstance initialisation will be completed in given time, though is a good hint. Usually 4*timeout would be the worst case (fail) scenario.

instanceId()

quint32 SingleInstance::instanceId ( ) const

nodiscard

Gets a unique identifier for the current instance.

instanceStarted

void SingleInstance::instanceStarted ( )

signal

isPrimary()

bool SingleInstance::isPrimary ( ) const

nodiscard

Gets if the instance is the primary instance.

isSecondary()

bool SingleInstance::isSecondary ( ) const

nodiscard

Gets if the instance is a secondary instance.

primaryPid()

qint64 SingleInstance::primaryPid ( ) const

nodiscard

Gets the process ID (PID) of the primary instance.

primaryUser()

QString SingleInstance::primaryUser ( ) const

nodiscard

Gets the username of the user running the primary instance.

receivedMessage

void SingleInstance::receivedMessage ( quint32 instanceId, QByteArray message )

signal

sendMessage()

bool SingleInstance::sendMessage	(	const QByteArray &	message,
		int	timeout = 100 )

Sends a message to the primary instance. Returns true on success.

Parameters

timeout	Timeout for connecting.
message

Returns

True on success.

Note

sendMessage() will return false if invoked from the primary. instance.

userData()

QStringList SingleInstance::userData ( ) const

nodiscard

Get the set user data.

---

The documentation for this class was generated from the following file:

• SingleInstance.h