Handles multiple instances of the same Application. More...

#include <singleapplication.h>

Inheritance diagram for SingleApplication:

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...

Detailed Description

Handles multiple instances of the same Application.

See also: QCoreApplication

Member Enumeration Documentation

◆ Mode

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.

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	The `SingleApplication` block should apply user wide (this adds user specific data to the key used for the shared memory and server name)
System	The `SingleApplication` block applies system-wide.
SecondaryNotification	Whether to trigger `instanceStarted()` even whenever secondary instances are started
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

◆ SendMode

enum SingleApplication::SendMode

Mode of operation of sendMessage.

Enumerator
BlockUntilPrimaryExit	Do not wait for the primary instance termination and return immediately

Constructor & Destructor Documentation

◆ SingleApplication()

SingleApplication::SingleApplication	(	int &	argc,
		char *	argv[],
		bool	allowSecondary = `false`,
		Options	options = `Mode::User`,
		int	timeout = `1000`,
		const QString &	userData = `{}`
	)

explicit

Intitializes a SingleApplication instance with argc command line arguments in argv.

argc - Number of arguments in argv
argv - Supplied command line arguments
allowSecondary - Whether to start the instance as secondary if there is already a primary instance.
mode - Whether for the SingleApplication block to be applied User wide or System wide.
timeout - Timeout to wait in milliseconds.
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 SingleApplication initialisation will be completed in given time, though is a good hint. Usually 4*timeout would be the worst case (fail) scenario.

See also
See the corresponding QAPPLICATION_CLASS constructor for reference

Member Function Documentation

◆ currentUser()

QString SingleApplication::currentUser ( ) const

Returns the username of the current user.

Returns: user name

◆ instanceId()

quint32 SingleApplication::instanceId ( ) const

Returns a unique identifier for the current instance.

Returns: instance id

◆ isPrimary()

bool SingleApplication::isPrimary ( ) const

Checks if the instance is primary instance.

Returns: true if the instance is primary

◆ isSecondary()

bool SingleApplication::isSecondary ( ) const

Checks if the instance is a secondary instance.

Returns: true if the instance is secondary

◆ primaryPid()

qint64 SingleApplication::primaryPid ( ) const

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

Returns: pid

◆ primaryUser()

QString SingleApplication::primaryUser ( ) const

Returns the username of the user running the primary instance.

Returns: user name

◆ sendMessage()

bool SingleApplication::sendMessage	(	const QByteArray &	message,
		int	timeout = `100`,
		SendMode	sendMode = `NonBlocking`
	)

Sends a message to the primary instance.

Parameters

message	data to send
timeout	timeout for connecting
sendMode	- Mode of operation

Returns: true on success

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

◆ userData()

QStringList SingleApplication::userData ( ) const

Get the set user data.

Returns: user data

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

singleapplication.h

Public Types

Signals

Public Member Functions