The QtServiceBase class provides an API for implementing Windows services and Unix daemons. More...

Inheritance diagram for QtServiceBase:

Public Types
enum	MessageType { Success = 0 , Error , Warning , Information }

enum	ServiceFlag { Default = 0x00 , CanBeSuspended = 0x01 , CannotBeStopped = 0x02 , NeedsStopOnShutdown = 0x04 }

Public Member Functions
	QtServiceBase (int argc, char **argv, const QString &name)

virtual	~QtServiceBase ()

QString	serviceName () const

QString	serviceDescription () const

void	setServiceDescription (const QString &description)

QtServiceController::StartupType	startupType () const

void	setStartupType (QtServiceController::StartupType startupType)

ServiceFlags	serviceFlags () const

void	setServiceFlags (ServiceFlags flags)

int	exec ()

void	logMessage (const QString &message, MessageType type=Success, int id=0, uint category=0, const QByteArray &data=QByteArray())

Static Public Member Functions
static QtServiceBase *	instance ()

Protected Member Functions
virtual void	start ()=0

virtual void	stop ()

virtual void	pause ()

virtual void	resume ()

virtual void	processCommand (int code)

virtual void	createApplication (int &argc, char **argv)=0

virtual int	executeApplication ()=0

Friends
class	QtServiceSysPrivate

Detailed Description

The QtServiceBase class provides an API for implementing Windows services and Unix daemons.

A Windows service or Unix daemon (a "service"), is a program that runs "in the background" independently of whether a user is logged in or not. A service is often set up to start when the machine boots up, and will typically run continuously as long as the machine is on.

Services are usually non-interactive console applications. User interaction, if required, is usually implemented in a separate, normal GUI application that communicates with the service through an IPC channel. For simple communication, QtServiceController::sendCommand() and QtService::processCommand() may be used, possibly in combination with a shared settings file. For more complex, interactive communication, a custom IPC channel should be used, e.g. based on Qt's networking classes. (In certain circumstances, a service may provide a GUI itself, ref. the "interactive" example documentation).

Typically, you will create a service by subclassing the QtService template class which inherits QtServiceBase and allows you to create a service for a particular application type.

The Windows implementation uses the NT Service Control Manager, and the application can be controlled through the system administration tools. Services are usually launched using the system account, which requires that all DLLs that the service executable depends on (i.e. Qt), are located in the same directory as the service, or in a system path.

On Unix a service is implemented as a daemon.

You can retrieve the service's description, state, and startup type using the serviceDescription(), serviceFlags() and startupType() functions respectively. The service's state is decribed by the ServiceFlag enum. The mentioned properites can also be set using the corresponding set functions. In addition you can retrieve the service's name using the serviceName() function.

Several of QtServiceBase's protected functions are called on requests from the QtServiceController class:

\list \o start() \o pause() \o processCommand() \o resume() \o stop() \endlist

You can control any given service using an instance of the QtServiceController class which also allows you to control services from separate applications. The mentioned functions are all virtual and won't do anything unless they are reimplemented. You can reimplement these functions to pause and resume the service's execution, as well as process user commands and perform additional clean-ups before shutting down.

QtServiceBase also provides the static instance() function which returns a pointer to an application's QtServiceBase instance. In addition, a service can report events to the system's event log using the logMessage() function. The MessageType enum describes the different types of messages a service reports.

The implementation of a service application's main function typically creates an service object derived by subclassing the QtService template class. Then the main function will call this service's exec() function, and return the result of that call. For example:

int main(int argc, char **argv)
{
    MyService service(argc, argv);
    return service.exec();
}

When the exec() function is called, it will parse the service specific arguments passed in argv, perform the required actions, and return.

\target serviceSpecificArguments

The following arguments are recognized as service specific:

\table \header \i Short \i Long \i Explanation \row \i -i \i -install \i Install the service. \row \i -u \i -uninstall \i Uninstall the service. \row \i -e \i -exec \i Execute the service as a standalone application (useful for debug purposes). This is a blocking call, the service will be executed like a normal application. In this mode you will not be able to communicate with the service from the contoller. \row \i -t \i -terminate \i Stop the service. \row \i -p \i -pause \i Pause the service. \row \i -r \i -resume \i Resume a paused service. \row \i -c {cmd} \i -command {cmd} \i Send the user defined command code {cmd} to the service application. \row \i -v \i -version \i Display version and status information. \endtable

If none of the arguments is recognized as service specific, exec() will first call the createApplication() function, then executeApplication() and finally the start() function. In the end, exec() returns while the service continues in its own process waiting for commands from the service controller.

See also: QtService, QtServiceController

Definition at line 103 of file qtservice.h.

Member Enumeration Documentation

◆ MessageType

enum QtServiceBase::MessageType

This enum describes the different types of messages a service reports to the system log.

\value Success An operation has succeeded, e.g. the service is started. \value Error An operation failed, e.g. the service failed to start. \value Warning An operation caused a warning that might require user interaction. \value Information Any type of usually non-critical information.

Definition at line 108 of file qtservice.h.

◆ ServiceFlag

enum QtServiceBase::ServiceFlag

This enum describes the different capabilities of a service.

\value Default The service can be stopped, but not suspended. \value CanBeSuspended The service can be suspended. \value CannotBeStopped The service cannot be stopped. \value NeedsStopOnShutdown (Windows only) The service will be stopped before the system shuts down. Note that Microsoft recommends this only for services that must absolutely clean up during shutdown, because there is a limited time available for shutdown of services.

Definition at line 113 of file qtservice.h.

Constructor & Destructor Documentation

◆ QtServiceBase()

QtServiceBase::QtServiceBase	(	int	argc,
		char **	argv,
		const QString &	name
	)

Creates a service instance called name. The argc and argv parameters are parsed after the exec() function has been called. Then they are passed to the application's constructor. The application type is determined by the QtService subclass.

The service is neither installed nor started. The name must not contain any backslashes or be longer than 255 characters. In addition, the name must be unique in the system's service database.

See also: exec(), start(), QtServiceController::install()

Definition at line 625 of file qtservice.cpp.

◆ ~QtServiceBase()

QtServiceBase::~QtServiceBase ( )

virtual

Destroys the service object. This neither stops nor uninstalls the service.

To stop a service the stop() function must be called explicitly. To uninstall a service, you can use the QtServiceController::uninstall() function.

See also: stop(), QtServiceController::uninstall()

Definition at line 667 of file qtservice.cpp.

Member Function Documentation

◆ createApplication()

void QtServiceBase::createApplication	(	int &	argc,
		char **	argv
	)

protectedpure virtual

Creates the application object using the argc and argv parameters.

This function is only called when no \l {serviceSpecificArguments}{service specific arguments} were passed to the service constructor, and is called by exec() before it calls the executeApplication() and start() functions.

The createApplication() function is implemented in QtService, but you might want to reimplement it, for example, if the chosen application type's constructor needs additional arguments.

See also: exec(), QtService

Implemented in QtService< Application >.

◆ exec()

int QtServiceBase::exec ( )

Executes the service.

When the exec() function is called, it will parse the \l {serviceSpecificArguments} {service specific arguments} passed in argv, perform the required actions, and exit.

If none of the arguments is recognized as service specific, exec() will first call the createApplication() function, then executeApplication() and finally the start() function. In the end, exec() returns while the service continues in its own process waiting for commands from the service controller.

See also: QtServiceController

Definition at line 758 of file qtservice.cpp.

◆ executeApplication()

int QtServiceBase::executeApplication ( )

protectedpure virtual

Executes the application previously created with the createApplication() function.

This function is only called when no \l {serviceSpecificArguments}{service specific arguments} were passed to the service constructor, and is called by exec() after it has called the createApplication() function and before start() function.

This function is implemented in QtService.

See also: exec(), createApplication()

Implemented in QtService< Application >.

◆ instance()

QtServiceBase * QtServiceBase::instance ( )

static

Returns a pointer to the current application's QtServiceBase instance.

Definition at line 873 of file qtservice.cpp.

◆ logMessage()

void QtServiceBase::logMessage	(	const QString &	message,
		QtServiceBase::MessageType	type = `Success`,
		int	id = `0`,
		uint	category = `0`,
		const QByteArray &	data = `QByteArray()`
	)

Reports a message of the given type with the given message to the local system event log. The message identifier id and the message category are user defined values. The data parameter can contain arbitrary binary data.

Message strings for id and category must be provided by a message file, which must be registered in the system registry. Refer to the MSDN for more information about how to do this on Windows.

See also: MessageType

Definition at line 445 of file qtservice_unix.cpp.

◆ pause()

void QtServiceBase::pause ( )

protectedvirtual

Reimplement this function to pause the service's execution (for example to stop a polling timer, or to ignore socket notifiers).

This function is called in reply to controller requests. The default implementation does nothing.

See also: resume(), QtServiceController::pause()

Definition at line 918 of file qtservice.cpp.

◆ processCommand()

void QtServiceBase::processCommand ( int code )

protectedvirtual

Reimplement this function to process the user command code.

This function is called in reply to controller requests. The default implementation does nothing.

See also: QtServiceController::sendCommand()

Definition at line 944 of file qtservice.cpp.

◆ resume()

void QtServiceBase::resume ( )

protectedvirtual

Reimplement this function to continue the service after a call to pause().

This function is called in reply to controller requests. The default implementation does nothing.

See also: pause(), QtServiceController::resume()

Definition at line 931 of file qtservice.cpp.

◆ serviceDescription()

QString QtServiceBase::serviceDescription ( ) const

Returns the description of the service.

See also: setServiceDescription(), serviceName()

Definition at line 688 of file qtservice.cpp.

◆ serviceFlags()

QtServiceBase::ServiceFlags QtServiceBase::serviceFlags ( ) const

Returns the service's state which is decribed using the ServiceFlag enum.

See also: ServiceFlags, setServiceFlags()

Definition at line 729 of file qtservice.cpp.

◆ serviceName()

QString QtServiceBase::serviceName ( ) const

Returns the name of the service.

See also: QtServiceBase(), serviceDescription()

Definition at line 678 of file qtservice.cpp.

◆ setServiceDescription()

void QtServiceBase::setServiceDescription ( const QString & description )

Sets the description of the service to the given description.

See also: serviceDescription()

Definition at line 698 of file qtservice.cpp.

◆ setServiceFlags()

void QtServiceBase::setServiceFlags ( ServiceFlags flags )

Sets the service's state to the state described by the given flags.

See also: ServiceFlags, serviceFlags()

Definition at line 474 of file qtservice_unix.cpp.

◆ setStartupType()

void QtServiceBase::setStartupType ( QtServiceController::StartupType type )

Sets the service's startup type to the given type.

See also: QtServiceController::StartupType, startupType()

Definition at line 718 of file qtservice.cpp.

◆ start()

void QtServiceBase::start ( )

protectedpure virtual

This function must be implemented in QtServiceBase subclasses in order to perform the service's work. Usually you create some main object on the heap which is the heart of your service.

The function is only called when no service specific arguments were passed to the service constructor, and is called by exec() after it has called the executeApplication() function.

Note that you don't need to create an application object or call its exec() function explicitly.

See also: exec(), stop(), QtServiceController::start()

◆ startupType()

QtServiceController::StartupType QtServiceBase::startupType ( ) const

Returns the service's startup type.

See also: QtServiceController::StartupType, setStartupType()

Definition at line 708 of file qtservice.cpp.

◆ stop()

void QtServiceBase::stop ( )

protectedvirtual

Reimplement this function to perform additional cleanups before shutting down (for example deleting a main object if it was created in the start() function).

This function is called in reply to controller requests. The default implementation does nothing.

See also: start(), QtServiceController::stop()

Definition at line 905 of file qtservice.cpp.

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

qtservice/qtservice.h
qtservice/qtservice.cpp
qtservice/qtservice_unix.cpp
qtservice/qtservice_win.cpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ MessageType

◆ ServiceFlag

Constructor & Destructor Documentation

◆ QtServiceBase()

◆ ~QtServiceBase()

Member Function Documentation

◆ createApplication()

◆ exec()

◆ executeApplication()

◆ instance()

◆ logMessage()

◆ pause()

◆ processCommand()

◆ resume()

◆ serviceDescription()

◆ serviceFlags()

◆ serviceName()

◆ setServiceDescription()

◆ setServiceFlags()

◆ setStartupType()

◆ start()

◆ startupType()

◆ stop()