The main interface to implement to create a service. More...

#include <service.h>

Inheritance diagram for QtService::Service:

Public Types
enum	CommandResult { OperationCompleted, OperationPending, OperationFailed, OperationExit, QT_SERVICE_POST_ENUM_DEPRECATED = OperationCompleted, QT_SERVICE_POST_ENUM_DEPRECATED = OperationCompleted }
	Indicates whether a service command has finished or needs to run asynchronously. More...

enum	TerminalMode { ReadOnly, WriteOnly, ReadWritePassive, ReadWriteActive }
	The modes a terminal can be in. More...

using	QT_SERVICE_POST_USING_DEPRECATED = CommandResult

Public Slots
void	quit ()
	Perform a graceful service stop. More...

void	reload ()
	Perform a reload command. More...

void	setTerminalActive (bool terminalActive)
	WRITE accessor for Service::terminalActive.

void	setTerminalMode (TerminalMode terminalMode)
	WRITE accessor for Service::terminalMode.

void	setGlobalTerminal (bool globalTerminal)
	WRITE accessor for Service::globalTerminal.

void	setStartWithTerminal (bool startWithTerminal)
	WRITE accessor for Service::startWithTerminal.

Signals
void	started (bool success)
	Must be emitted when starting was completed if onStart returned OperationPending.

Q_DECL_DEPRECATED void	started ()

void	stopped (int exitCode=EXIT_SUCCESS)
	Must be emitted when stopping was completed if onStop returned OperationPending.

void	reloaded (bool success)
	Must be emitted when reloading was completed if onReload returned OperationPending.

Q_DECL_DEPRECATED void	reloaded ()

void	paused (bool success)
	Must be emitted when pausing was completed if onPause returned OperationPending.

Q_DECL_DEPRECATED void	paused ()

void	resumed (bool success)
	Must be emitted when resuming was completed if onResume returned OperationPending.

Q_DECL_DEPRECATED void	resumed ()

void	terminalActiveChanged (bool terminalActive, QPrivateSignal)
	NOTIFY accessor for Service::terminalActive.

void	terminalModeChanged (TerminalMode terminalMode, QPrivateSignal)
	NOTIFY accessor for Service::terminalMode.

void	globalTerminalChanged (bool globalTerminal, QPrivateSignal)
	NOTIFY accessor for Service::globalTerminal.

void	startWithTerminalChanged (bool startWithTerminal, QPrivateSignal)
	NOTIFY accessor for Service::startWithTerminal.

Public Member Functions
	Service (int &argc, char **argv, int=QCoreApplication::ApplicationFlags)
	Constructs a new service from the main arguments. More...

int	exec ()
	Starts the service execution. More...

Q_INVOKABLE QList< int >	getSockets (const QByteArray &socketName)
	Returns all activated sockets found for the given name. More...

Q_INVOKABLE int	getSocket ()
	Returns the default activated socket, if one exists. More...

QString	backend () const
	READ accessor for Service::backend.

QDir	runtimeDir () const
	READ accessor for Service::runtimeDir.

bool	isTerminalActive () const
	READ accessor for Service::terminalActive.

TerminalMode	terminalMode () const
	READ accessor for Service::terminalMode.

bool	isGlobalTerminal () const
	READ accessor for Service::globalTerminal.

bool	startWithTerminal () const
	READ accessor for Service::startWithTerminal.

Public Member Functions inherited from QObject
virtual const QMetaObject *	metaObject () const const

virtual void *	qt_metacast (const char *)

virtual int	qt_metacall (QMetaObject::Call, int, void **)

	QObject (QObject *parent)

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

QString	objectName () const const

void	setObjectName (const QString &name)

bool	isWidgetType () const const

bool	isWindowType () const const

bool	signalsBlocked () const const

bool	blockSignals (bool block)

QThread *	thread () const const

void	moveToThread (QThread *targetThread)

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)

void	killTimer (int id)

T	findChild (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const

const QObjectList &	children () const const

void	setParent (QObject *parent)

void	installEventFilter (QObject *filterObj)

void	removeEventFilter (QObject *obj)

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const const

bool	disconnect (const char signal, const QObject receiver, const char *method) const const

bool	disconnect (const QObject receiver, const char method) const const

void	dumpObjectTree ()

void	dumpObjectInfo ()

void	dumpObjectTree () const const

void	dumpObjectInfo () const const

bool	setProperty (const char *name, const QVariant &value)

QVariant	property (const char *name) const const

QList< QByteArray >	dynamicPropertyNames () const const

void	destroyed (QObject *obj)

void	objectNameChanged (const QString &objectName)

QObject *	parent () const const

bool	inherits (const char *className) const const

void	deleteLater ()

Static Public Member Functions
static Service *	instance ()
	Returns a reference to the currently running service. More...

Static Public Member Functions inherited from QObject
QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

Protected Slots
virtual void	terminalConnected (Terminal *terminal)
	Is called by the backend for every newly connected terminal. More...

Protected Member Functions
virtual bool	preStart ()
	Fallback method for otherwise impossible early setup (try to not use it) More...

virtual CommandResult	onStart ()=0
	Is called by the backend to start the service. More...

virtual CommandResult	onStop (int &exitCode)
	Is called by the backend to stop the service. More...

virtual CommandResult	onReload ()
	Is called by the backend to reload the service. More...

virtual CommandResult	onPause ()
	Is called by the backend to pause the service. More...

virtual CommandResult	onResume ()
	Is called by the backend to resume the service. More...

virtual QVariant	onCallback (const QByteArray &kind, const QVariantList &args)
	Is called by the backend if a platform specific callback was triggered. More...

virtual bool	verifyCommand (const QStringList &arguments)
	Is called from the terminal process to perform early CLI validation. More...

void	addCallback (const QByteArray &kind, const std::function< QVariant(QVariantList)> &fn)
	Adds a callback to be called by onCallback for the given kind. More...

template<typename TFunction >
void	addCallback (const QByteArray &kind, const TFunction &fn)
	Adds a callback to be called by onCallback for the given kind. More...

template<typename TClass , typename TReturn , typename... TArgs>
void	addCallback (const QByteArray &kind, TReturn(TClass::fn)(TArgs...), std::enable_if_t< std::is_base_of< QtService::Service, TClass >::value, void >=nullptr)
	Adds a callback to be called by onCallback for the given kind. More...

Protected Member Functions inherited from QObject
QObject *	sender () const const

int	senderSignalIndex () const const

int	receivers (const char *signal) const const

bool	isSignalConnected (const QMetaMethod &signal) const const

virtual void	timerEvent (QTimerEvent *event)

virtual void	childEvent (QChildEvent *event)

virtual void	customEvent (QEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	disconnectNotify (const QMetaMethod &signal)

Properties
QString	backend
	The backend this service is currently run with. More...

QDir	runtimeDir
	The runtime directory this service should place runtime files in. More...

bool	terminalActive
	Specifies whether the service accepts terminals. More...

TerminalMode	terminalMode
	Specifies the mode new terminals are started as. More...

bool	globalTerminal
	Specifies whether terminals from all users can connect, or only of the same user as the service. More...

bool	startWithTerminal
	Specifies whether terminals should try to start the service if it is not running. More...

Properties inherited from QObject
	objectName

Detailed Description

The main interface to implement to create a service.

This class is the primary interface for a service. In your own service, you will implement this class and use it as replacement for QCoreApplication:

int main(int argc, char *argv[])
{
    MyService service{argc, argv}; // extends QtService::Service
    return service.exec();
}

Rules of usage:**
You should always follow the following rules when using/creating a service:

Do not create a QCoreApplication yourself - this is done internally
Use the same constructor signature to pass the main arguments. It is very important that the argc argument is passed as reference! Passing as value will crash your application
Do nothing else in the main besides setting the serices properties that need to be set early! Any setup etc. must all be done in the Service::onStart method!!! (The properties that need to be set early all have a hint in their documentation)
Never call QCoreApplication::quit (or QCoreApplication::exit)! Use Service::quit instead
Do not rely on QCoreApplication::aboutToQuit, as this may not be emitted at all, or on some arbitrary point. Put all cleanup code in the Service::onStop method
Be careful with Service::preStart - only use it when you have no other choice

Definition at line 37 of file service.h.

Member Enumeration Documentation

◆ CommandResult

enum QtService::Service::CommandResult

Indicates whether a service command has finished or needs to run asynchronously.

Enumerator
OperationCompleted	The command was successfully completed synchronously.
OperationPending	The command is beeing proccessed asynchronously and the service will emit the corresponding signal once it's done.
OperationFailed	The command failed synchronously. The system may exit the service afterwards.
OperationExit	The command executed successfully, but the service should still exit. Only usable from onStart()
QT_SERVICE_POST_ENUM_DEPRECATED	Deprecated: Deprecated. Use OperationCompleted instead Deprecated: Deprecated. Use OperationPending instead
QT_SERVICE_POST_ENUM_DEPRECATED	Deprecated: Deprecated. Use OperationCompleted instead Deprecated: Deprecated. Use OperationPending instead

Definition at line 57 of file service.h.

◆ TerminalMode

enum QtService::Service::TerminalMode

The modes a terminal can be in.

Enumerator
ReadOnly	The terminal can only receive data from the service. Useful for machine-to-machine communication.
WriteOnly	The terminal can only send data to the service. Useful for machine-to-machine communication.
ReadWritePassive	The terminal can read and write as much as it wants. Useful for machine-to-machine communication.
ReadWriteActive	The terminal can read and write, but writing is limited to what the service requests. Recommended for humans using the terminal.

Definition at line 79 of file service.h.

Constructor & Destructor Documentation

◆ Service()

QtService::Service::Service	(	int &	argc,
		char **	argv,
		int	= `QCoreApplication::ApplicationFlags`
	)

explicit

Constructs a new service from the main arguments.

Parameters

argc	The `argc` argument of the main
argv	The `argv` argument of the main

Create a service from the arguments passed to the application

Attention: It is very important that the first parameter is a reference! When implementing this interface, make shure your constructor has the the two arg parameters and the the argc argument is a reference as well! Passing by value will crash your application!

Member Function Documentation

◆ addCallback() [1/3]

QtService::Service::addCallback	(	const QByteArray &	kind,
		const std::function< QVariant(QVariantList)> &	fn
	)

protected

Adds a callback to be called by onCallback for the given kind.

Parameters

kind	The kind of command the callback should be registered for
fn	The function to be called on such a command

By using this method you can register a function as callback. When a comand of the given kind is send to the service the default implementation of the Service::onCallback method will call this callback with the arguments it received and return the value returned by it.

◆ addCallback() [2/3]

template<typename TFunction >

QtService::Service::addCallback	(	const QByteArray &	kind,
		const TFunction &	fn
	)

protected

Adds a callback to be called by onCallback for the given kind.

Template Parameters

TFunction The type of the functor to be called

Parameters

kind	The kind of command the callback should be registered for
fn	The function to be called on such a command

By using this method you can register a function as callback. When a comand of the given kind is send to the service the default implementation of the Service::onCallback method will call this callback with the arguments it received and return the value returned by it.

This version will automatically convert the QVariantList arguments to the types that are required by the given method and convert the returned value back to QVariant. Please make shure the arguments types match the ones declared by the service backend, as different number or types can crash your application. Also, make shure all used types are registered to the metatype system via #Q_DECLARE_METATYPE - otherwise the conversions will fail to compile.

See also: Supported Service Backends, Service::onCallback, ServiceControl::callCommand

Definition at line 202 of file service.h.

◆ addCallback() [3/3]

template<typename TClass , typename TReturn , typename... TArgs>

QtService::Service::addCallback	(	const QByteArray &	kind,
		TReturn(TClass::*)(TArgs...)	fn,
		std::enable_if_t< std::is_base_of< QtService::Service, TClass >::value, void *>	= `nullptr`
	)

protected

Adds a callback to be called by onCallback for the given kind.

Template Parameters

TClass	The type of your service subclass. Must extend QtService::Service
TReturn	The return-type of the class member
TArgs	The arguments of the class member

Parameters

kind	The kind of command the callback should be registered for
fn	The function to be called on such a command

By using this method you can register a function as callback. When a comand of the given kind is send to the service the default implementation of the Service::onCallback method will call this callback with the arguments it received and return the value returned by it.

With this overload you can pass a member function as callback to the service. The service will automatically bind it to the calling instance and then pass the method on to the generic function overload to perform the parameter conversions. (The 3rd parameter is only used as a compiler trick, it is never used and you should never pass anything as the 3rd argument)

This version will automatically convert the QVariantList arguments to the types that are required by the given method and convert the returned value back to QVariant. Please make shure the arguments types match the ones declared by the service backend, as different number or types can crash your application. Also, make shure all used types are registered to the metatype system via #Q_DECLARE_METATYPE - otherwise the conversions will fail to compile.

See also: Supported Service Backends, Service::onCallback, ServiceControl::callCommand

Definition at line 208 of file service.h.

◆ exec()

QtService::Service::exec ( )

Starts the service execution.

Returns: The exit code of the application that should be returned from the main.

This method is blocking and will internally call QCoreApplication::exec at some point. In other words this method starts the service as well as the main event loop.

◆ getSocket()

QtService::Service::getSocket ( )

Returns the default activated socket, if one exists.

Returns: The default socket descriptor, if one exists, otherwise -1

On services that supports socket activation, you can retrieve an activated sockets with this method. If the backend supports getting the default, unnamed socket, then this method is an easy way to get it. If you want multiple sockets or can access them by name only, use Service::getSockets instead.

The returned socket can be used with classes like QTcpServer, QLocalServer or QWebSocketServer. All of these classes have a method to set an already activated socket descriptor they can work with.

See also: Service::getSockets, QTcpServer::setSocketDescriptor, QLocalServer::listen(qintptr), QWebSocketServer::setSocketDescriptor, http://0pointer.de/blog/projects/socket-activation.html

◆ getSockets()

QtService::Service::getSockets ( const QByteArray & socketName )

Returns all activated sockets found for the given name.

Parameters

socketName The name of the socket to be retrieved

Returns: The socket descriptors associated with that name

On services that supports socket activation, you can retrieve the activated sockets with this method. Typically, only one socket is found per name, but sometimes you may want to listen on different interfaces for the same service, thus it is possible multiple sockets share an identity. In case you only have a single unnamed socket, use Service::getSocket instead

The returned sockets can be used with classes like QTcpServer, QLocalServer or QWebSocketServer. All of these classes have a method to set an already activated socket descriptor they can work with.

See also: Service::getSocket, QTcpServer::setSocketDescriptor, QLocalServer::listen, QWebSocketServer::setSocketDescriptor, http://0pointer.de/blog/projects/socket-activation.html

◆ instance()

QtService::Service::instance ( )

static

Returns a reference to the currently running service.

Returns: The current service instance

This is only set when actually running as service and the service has been created. Otherwise, nullptr is returned

See also: qService

◆ onCallback()

QtService::Service::onCallback	(	const QByteArray &	kind,
		const QVariantList &	args
	)

protectedvirtual

Is called by the backend if a platform specific callback was triggered.

Returns: The callbacks return value

Parameters

kind	The kind of command that is beeing handeled
args	The arguments of that command

This method is called by the backend for any kind of custom command. The parameters and return value of the command depend on the kind of command it is. Check the Supported Service Backends documentation for a list of callbacks for each service backend.

Typically, you don't need to implement this method yourself. Instead, simply register a member of your service class as callback for a specific kind. That method will then be called by the default implementation of this method. Example:

// in your service contructor:
addCallback("doStuff", &MyService::doStuff);
// in the cpp file:
// IMPORTANT: this signature must match the one declared by the service backend!
int MyService::doStuff(int p1, double p2) {
    qDebug() << "Custom callback doStuff called with" << p1 << p2;
    return p1;
}

See also: Supported Service Backends, Service::addCallback, ServiceControl::callCommand

◆ onPause()

QtService::Service::onPause ( )

protectedvirtual

Is called by the backend to pause the service.

Returns: The command state after the method returned

This method is called by the service manager if the serivce should pause whatever it is currently doing. Use the method to pause running operations like stopping accepting on sockets or pausing asynchronours calculations.

Also, depending on the serice backend your process may halt excution after entering the paused state, which means your service will actually stop running until it is resumed - however this behaviour is inconsistent on different platforms and you should never rely on it, only be prepared.

This method can behave in 2 ways. If you return Service::OperationCompleted, that the service engine assumes that pause has successfully been completed and the service leaves the "pausing" state and enters the "paused" state. However, you might need to perform an asynchronous operation during the pause. In that case Service::OperationPending can be returned to indicate that pausing has not been completed yet. The service will remain in the pausing state until you emit Servie::paused. Please note that beeing in the pausing state is also known by the service manager. Depending on the service backend this state may time out leading to the manager killing off your process if it takes to long. In case the application encounters an error, you can abort the command by either returning Service::OperationFailed for a synchronous fail or emit started with a fals result for asynchronous operations.

Attention: Never emit the paused signal and return anything but Service::OperationPending - this will most likely crash your application. You can always emit the paused signal from within this method and simply return Service::OperationPending - it will give you the same result as only returning Service::OperationCompleted (or Service::OperationFailed), but allows you to emit the signal yourself. This is useful if the pausing operation may or may not be asynchronous.

See also: Service::CommandMode, Service::paused, Service::onResume

◆ onReload()

QtService::Service::onReload ( )

protectedvirtual

Is called by the backend to reload the service.

Returns: The command state after the method returned

This method can be called any time while the service is in it's running state. It is typically used by the service manager to tell the service that some configurations have changed and that it should reload those - it's basically a faster alternative to restarting the whole service.

This method can behave in 2 ways. If you return Service::OperationCompleted, that the service engine assumes that reload has successfully been completed and the service leaves the "reloading" state and goes back to the the "running" state. However, you might need to perform an asynchronous operation during the reload (like reconnecting to some dependend service). In that case Service::OperationPending can be returned to indicate that reloading has not been completed yet. The service will remain in the reloading state until you emit Servie::reloaded. Please note that beeing in the reloading state is also known by the service manager. Depending on the service backend this state may time out leading to the manager killing off your process if it takes to long. In case the application encounters an error, you can abort the command by either returning Service::OperationFailed for a synchronous fail or emit started with a fals result for asynchronous operations.

Attention: Never emit the reloaded signal and return anything but Service::OperationPending - this will most likely crash your application. You can always emit the reloaded signal from within this method and simply return Service::OperationPending - it will give you the same result as only returning Service::OperationCompleted (or Service::OperationFailed), but allows you to emit the signal yourself. This is useful if the reloading operation may or may not be asynchronous.

See also: Service::CommandMode, Service::reloaded

◆ onResume()

QtService::Service::onResume ( )

protectedvirtual

Is called by the backend to resume the service.

Returns: The command state after the method returned

This method is called by the service manager if the service should resume it's work after having been paused. This method is called by the backend as soon as the process continues it's execution. You can use the method to continue whatever you paused in Service::onPause.

This method can behave in 2 ways. If you return Service::OperationCompleted, that the service engine assumes that resume has successfully been completed and the service leaves the "resuming" state and enters the "running" state again. However, you might need to perform an asynchronous operation during the resume. In that case Service::OperationPending can be returned to indicate that resuming has not been completed yet. The service will remain in the resuming state until you emit Servie::resumed. Please note that beeing in the resuming state is also known by the service manager. Depending on the service backend this state may time out leading to the manager killing off your process if it takes to long. In case the application encounters an error, you can abort the command by either returning Service::OperationFailed for a synchronous fail or emit started with a fals result for asynchronous operations.

Attention: Never emit the resumed signal and return anything but Service::OperationPending - this will most likely crash your application. You can always emit the resumed signal from within this method and simply return Service::OperationPending - it will give you the same result as only returning Service::OperationCompleted (or Service::OperationFailed), but allows you to emit the signal yourself. This is useful if the resuming operation may or may not be asynchronous.

See also: Service::CommandMode, Service::resumed, Service::onPause

◆ onStart()

QtService::Service::onStart ( )

protectedpure virtual

Is called by the backend to start the service.

Returns: The command state after the method returned

At the point this method is called first thing after the eventloop has started and the service setup part of the backends has been completed. The service can now start doing it's actual work. Use this method to create the stuff your service needs to run, like starting servers etc.

This method can behave in 4 ways. If you return Service::OperationCompleted, the service engine assumes that startup has successfully been completed and the service leaves the "starting" state and enters the "running" state. However, you might need to perform an asynchronous operation during startup (like connecting to some dependend service). In that case Service::OperationPending can be returned to indicate that starting has not been completed yet. The service will remain in the starting state until you emit Servie::started. Please note that beeing in the starting state is also known by the service manager. Depending on the service backend this state may time out leading to the manager killing off your process if it takes to long. In case the application encounters an error, you can abort the command by either returning Service::OperationFailed for a synchronous fail or emit started with a fals result for asynchronous operations.

One special return value for the start command only is Service::OperationExit. It's the same as Service::OperationCompleted, but tells the system to stop the service immediatly after. This allows you to create "one-shot" style services that only do something when started and the quit.

Attention: Never emit the started signal and return anything but Service::OperationPending - this will most likely crash your application. You can always emit the started signal from within this method and simply return Service::OperationPending - it will give you the same result as only returning Service::OperationCompleted (or Service::OperationFailed), but allows you to emit the signal yourself. This is useful if the startup operation may or may not be asynchronous.

See also: Service::CommandMode, Service::started, Service::onStop

◆ onStop()

QtService::Service::onStop ( int & exitCode )

protectedvirtual

Is called by the backend to stop the service.

Parameters

exitCode [out] You can set this to the code your service should exit with

Returns: The command state after the method returned

This method is called by the backends if the service received a request to stop. Use this method to clean up stuff, close connections etc.

This method can behave in 3 ways. If you return Service::OperationCompleted, that the service engine assumes that stop has successfully been completed and the service leaves the "stopping" state and the proccess will quit after the backend completed it's internal cleanups. However, you might need to perform an asynchronous operation during the stop (like writing remaining data). In that case Service::OperationPending can be returned to indicate that stopping has not been completed yet. The service will remain in the stopping state until you emit Servie::stopped. Please note that beeing in the stopping state is also known by the service manager. Depending on the service backend this state may time out leading to the manager killing off your process if it takes to long.

In case you run the method synchronous, you can report an exit code to the parameter. If you don't set it, it will be set to EXIT_SUCCESS - aka 0 on most platforms. For asynchronous stopping, use the signal parameter instead.

Attention: Never emit the stopped signal and return anything but Service::OperationPending - this will most likely crash your application. You can always emit the stopped signal from within this method and simply return Service::OperationPending - it will give you the same result as only returning Service::OperationCompleted (or Service::OperationFailed), but allows you to emit the signal yourself. This is useful if the stopping operation may or may not be asynchronous.

See also: Service::CommandMode, Service::stopped, Service::onStart

◆ paused

Q_DECL_DEPRECATED void QtService::Service::paused ( )

signal

Deprecated:: Use paused(bool) instead

◆ preStart()

QtService::Service::preStart ( )

protectedvirtual

Fallback method for otherwise impossible early setup (try to not use it)

Returns: true if the service can continue to start, false if it should abort starting and exit

This method can be used to perform startup operations that must be done before the eventloop starts. At the point of the method beeing called the QCoreApplication already exists and logging has been set up (however, depending on the platform might not work correctly yet). The services state however is uncertain and not ready yet.

Warning: Generally, you should not implement this method as it is called in an early state where the serivce is not completely initialized! Do everything you can in Service::onStart. Only when you need to do something that cannot be done after the eventloop started, do it here. (For example if you need to capture an early event with a custom event listener that would be missed otherwise or to set a customlogging message pattern)

See also: Service::onStart

◆ quit

QtService::Service::quit ( )

slot

Perform a graceful service stop.

Stops the service by using the appropriate method to do so for each backend. Use this method instead of QCoreApplication::quit (and QCoreApplication::exit), as the latter will not do a proper stop!

This method will initialize the stop which will eventually lead to Service::onStop beeing called and the service to quit

See also: Service::onStop

◆ reload

QtService::Service::reload ( )

slot

Perform a reload command.

This method will notify the service manager that the service is about to reload and the call Service::onReload. This allows you to perform some kind of reload operation without the service manager triggering it, but still report that it is happening to the manager.

See also: Service::onReload

◆ reloaded

Q_DECL_DEPRECATED void QtService::Service::reloaded ( )

signal

Deprecated:: Use reloaded(bool) instead

◆ resumed

Q_DECL_DEPRECATED void QtService::Service::resumed ( )

signal

Deprecated:: Use resumed(bool) instead

◆ started

Q_DECL_DEPRECATED void QtService::Service::started ( )

signal

Deprecated:: Use started(bool) instead

◆ terminalConnected

QtService::Service::terminalConnected ( Terminal * terminal )

protectedvirtualslot

Is called by the backend for every newly connected terminal.

Parameters

terminal The connected terminal

This methods is called internally if terminal mode is enabled and a terminal has connected. The whole initialization is done internally, which means at this point the terminal is connected and ready to be used. The commands are also already available at this point.

The ownership of the terminal is transferred to this method, whichs means your implementation must now take care of the terminal. The terminals parent object will already be this service instance.

Note: The default implementation will simply disconnect the terminal again and let it delete itself once disconnected.

See also: Terminal, Service::terminalActive

◆ verifyCommand()

QtService::Service::verifyCommand ( const QStringList & arguments )

protectedvirtual

Is called from the terminal process to perform early CLI validation.

Parameters

arguments The terminal client arguments

Returns: true if the arguments are valid, false if not

This method is called on a Terminal client (i.e. not the service process, but the terminal client process) before it tries to connect to the service. You can implement to provide an early validation of command line arguments which leads to a better experience when using terminals.

The arguments are pre-filtered, which means the application name as well as QtService-specific arguments do not appear here. So for example, the command service.exe --terminal --backend windows hello world can be retrieved from this property as ["hello", "world"]

See also: Terminal, Service::terminalConnected, Terminal::command

Property Documentation

◆ backend

QtService::Service::backend

read

The backend this service is currently run with.

Default: standard

This is set by the backend which is internally used to run the service. The backend can be selected by the --backend <backend> command.

Accessors
READ	backend()
CONSTANT

Definition at line 42 of file service.h.

◆ globalTerminal

QtService::Service::globalTerminal

readwrite

Specifies whether terminals from all users can connect, or only of the same user as the service.

Default: false

In local mode (the default) only terminals started from the same user account as the one the service is running as can access the service. This is fine for user-mode services, but system services typically run as system user.

When in global mode, anyone can connect to the service, effectively bridging that barrier.

Note: Changing this property after activating terminals (setting Service::terminalActive to true) has no effect. Either set this property beforehand or disable and reenable the former after changing this one.

Warning: In global mode, ANY user has access to the service, and can send commands to it. You should be very careful when exposing a service to the whole system, as it can lead to potential security risks, especially when the service is running as system service.

Accessors
READ	globalTerminal()
WRITE	setGlobalTerminal()
NOTIFY	globalTerminalChanged()

See also: Terminal, Service::terminalActive

Definition at line 51 of file service.h.

◆ runtimeDir

QtService::Service::runtimeDir

read

The runtime directory this service should place runtime files in.

Default: Platform dependend

The runtime directory to be used to place sockets, lockfiles and other temporary stuff. This directoy may be managed by the underlying service framework and is the same as reported by the service control

Accessors
READ	runtimeDir()
CONSTANT

See also: ServiceControl::runtimeDir

Definition at line 44 of file service.h.

◆ startWithTerminal

QtService::Service::startWithTerminal

readwrite

Specifies whether terminals should try to start the service if it is not running.

Default: false

If enabled, the terminal client will use the ServiceControl of the corresponding service backend to determine whether the service is already running, and if not start it.

This of course will only work if the service supports starting. If status information is supported, the terminals will use that to check the state. Otherwise the simply to start in a fire and forget manner and then try to connect.

Note: This property is evaluated from the terminals themselves, which means you should set it before calling Service::exec. Changing it on the service instance will have no effect.

Accessors
READ	startWithTerminal()
WRITE	setStartWithTerminal()
NOTIFY	startWithTerminalChanged()

See also: Terminal, Service::terminalActive, ServiceControl, ServiceControl::SupportsStart, ServiceControl::SupportsStatus

Definition at line 53 of file service.h.

◆ terminalActive

QtService::Service::terminalActive

readwrite

Specifies whether the service accepts terminals.

Default: false

Set this property to true to enable the internal terminal server. When activated, terminals that are created via --terminal can connect to the service. Otherwise they won't be able to.

Note: Terminals won't even try to connect if this property is not set. Thus you should always set this property before calling Service::exec. If you want to device whether you want terminals dynamically, simply set this property to false again in the Service::preStart or Service::onStart methods.

Accessors
READ	isTerminalActive()
WRITE	setTerminalActive()
NOTIFY	terminalActiveChanged()

See also: Terminal, Service::terminalConnected, Service::terminalMode, Service::globalTerminal, Service::startWithTerminal

Definition at line 47 of file service.h.

◆ terminalMode

QtService::Service::terminalMode

readwrite

Specifies the mode new terminals are started as.

Default: Service::ReadWriteActive

The terminal mode that terminal clients should use to connect to the service with. The mode determines how I/O is managed between the service and the terminal. The general recommendation is to design a terminal for Service::ReadWriteActive when it is intended to be used by a human, and use one of the other 3 for machine to machine communication, choosing whichever directions of communication are needed.

Please note that this property is evaluated from the terminals themselves, which means you should set it before calling Service::exec. Changing it on the service instance will have no effect.

Note: For the active mode, the user won't be able to input anything unless the Terminal::request* (or Terminal::await*) methods are called.

Accessors
READ	terminalMode()
WRITE	setTerminalMode()
NOTIFY	terminalModeChanged()

See also: Terminal, Service::terminalActive, Terminal::terminalMode, Terminal::requestChar, Terminal::requestChars, Terminal::requestLine, Terminal::awaitChar, Terminal::awaitChars, Terminal::awaitLine

Definition at line 49 of file service.h.

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

service.h
service.dox

Public Types

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Protected Slots

Protected Member Functions

Properties

Detailed Description

Member Enumeration Documentation

◆ CommandResult

◆ TerminalMode

Constructor & Destructor Documentation

◆ Service()

Member Function Documentation

◆ addCallback() [1/3]

◆ addCallback() [2/3]

◆ addCallback() [3/3]

◆ exec()

◆ getSocket()

◆ getSockets()

◆ instance()

◆ onCallback()

◆ onPause()

◆ onReload()

◆ onResume()

◆ onStart()

◆ onStop()

◆ paused

◆ preStart()

◆ quit

◆ reload

◆ reloaded

◆ resumed

◆ started

◆ terminalConnected

◆ verifyCommand()

Property Documentation

◆ backend

◆ globalTerminal

◆ runtimeDir

◆ startWithTerminal

◆ terminalActive

◆ terminalMode