|  | Home

# QtServiceController Class Reference

The QtServiceController class allows you to control services from separate applications. More...

     #include <QtServiceController>

- List of all members, including inherited members

### Public Types

- enum StartupType { AutoStartup, ManualStartup }

### Public Functions

- QtServiceController ( const QString & name )
- virtual ~QtServiceController ()
- bool isInstalled () const
- bool isRunning () const
- bool pause ()
- bool resume ()
- bool sendCommand ( int code )
- QString serviceDescription () const
- QString serviceFilePath () const
- QString serviceName () const
- bool start ( const QStringList & arguments )
- bool start ()
- StartupType startupType () const
- bool stop ()
- bool uninstall ()

### Static Public Members

- bool install ( const QString & serviceFilePath, const QString & account = QString(), const QString & password = QString() )

## Detailed Description

The QtServiceController class allows you to control services from separate applications.

QtServiceController provides a collection of functions that lets you install and run a service controlling its execution, as well as query its status.

In order to run a service, the service must be installed in the system's service database using the install() function. The system will start the service depending on the specified StartupType; it can either be started during system startup, or when a process starts it manually.

Once a service is installed, the service can be run and controlled manually using the start(), stop(), pause(), resume() or sendCommand() functions. You can at any time query for the service's status using the isInstalled() and isRunning() functions, or you can query its properties using the serviceDescription(), serviceFilePath(), serviceName() and startupType() functions. For example:

     MyService service;       \\ which inherits QtService
     QString serviceFilePath;

     QtServiceController controller(service.serviceName());

     if (controller.install(serviceFilePath))
         controller.start()

     if (controller.isRunning())
         QMessageBox::information(this, tr("Service Status"),
                                  tr("The %1 service is started").arg(controller.serviceName()));

     ...

     controller.stop();
     controller.uninstall();
     }

An instance of the service controller can only control one single service. To control several services within one application, you must create en equal number of service controllers.

The QtServiceController destructor neither stops nor uninstalls the associated service. To stop a service the stop() function must be called explicitly. To uninstall a service, you can use the uninstall() function.

See also QtServiceBase and QtService.

## Member Type Documentation

### enum QtServiceController::StartupType

This enum describes when a service should be started.

Constant | Value | Description
--- | --- | ---
`QtServiceController::AutoStartup` | `0` | The service is started during system startup.
`QtServiceController::ManualStartup` | `1` | The service must be started manually by a process.

Warning: The StartupType enum is ignored under UNIX-like systems. A service, or daemon, can only be started manually on such systems with current implementation.

See also startupType().

## Member Function Documentation

### QtServiceController::QtServiceController ( const QString & name )

Creates a controller object for the service with the given name.

### QtServiceController::~QtServiceController () `[virtual]`

Destroys the service controller. This neither stops nor uninstalls the controlled service.

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

See also stop() and QtServiceController::uninstall().

### bool QtServiceController::install ( const QString & serviceFilePath, const QString & account = QString(), const QString & password = QString() ) `[static]`

Installs the service with the given serviceFilePath and returns true if the service is installed successfully; otherwise returns false.

On Windows service is installed in the system's service control manager with the given account and password.

On Unix service configuration is written to QSettings::SystemScope using "QtSoftware" as organization name. account and password arguments are ignored.

Warning: Due to the different implementations of how services (daemons) are installed on various UNIX-like systems, this method doesn't integrate the service into the system's startup scripts.

See also uninstall() and start().

### bool QtServiceController::isInstalled () const

Returns true if the service is installed; otherwise returns false.

On Windows it uses the system's service control manager.

On Unix it checks configuration written to QSettings::SystemScope using "QtSoftware" as organization name.

See also install().

### bool QtServiceController::isRunning () const

Returns true if the service is running; otherwise returns false. A service must be installed before it can be run using a controller.

See also start() and isInstalled().

### bool QtServiceController::pause ()

Requests the running service to pause. If the service's state is QtServiceBase::CanBeSuspended, the service will call the QtServiceBase::pause() implementation. The function does nothing if the service is not running.

Returns true if a running service was successfully paused; otherwise returns false.

See also resume(), QtServiceBase::pause(), and QtServiceBase::ServiceFlags.

### bool QtServiceController::resume ()

Requests the running service to continue. If the service's state is QtServiceBase::CanBeSuspended, the service will call the QtServiceBase::resume() implementation. This function does nothing if the service is not running.

Returns true if a running service was successfully resumed; otherwise returns false.

See also pause(), QtServiceBase::resume(), and QtServiceBase::ServiceFlags.

### bool QtServiceController::sendCommand ( int code )

Sends the user command code to the service. The service will call the QtServiceBase::processCommand() implementation. This function does nothing if the service is not running.

Returns true if the request was sent to a running service; otherwise returns false.

See also QtServiceBase::processCommand().

### QString QtServiceController::serviceDescription () const

Returns the description of the controlled service.

See also install() and serviceName().

### QString QtServiceController::serviceFilePath () const

Returns the file path to the controlled service.

See also install() and serviceName().

### QString QtServiceController::serviceName () const

Returns the name of the controlled service.

See also QtServiceController() and serviceDescription().

### bool QtServiceController::start ( const QStringList & arguments )

Starts the installed service passing the given arguments to the service. A service must be installed before a controller can run it.

Returns true if the service could be started; otherwise returns false.

See also install() and stop().

### bool QtServiceController::start ()

This is an overloaded member function, provided for convenience.

Starts the installed service without passing any arguments to the service.

### StartupType QtServiceController::startupType () const

Returns the startup type of the controlled service.

See also install() and serviceName().

### bool QtServiceController::stop ()

Requests the running service to stop. The service will call the QtServiceBase::stop() implementation unless the service's state is QtServiceBase::CannotBeStopped. This function does nothing if the service is not running.

Returns true if a running service was successfully stopped; otherwise false.

See also start(), QtServiceBase::stop(), and QtServiceBase::ServiceFlags.

### bool QtServiceController::uninstall ()

Uninstalls the service and returns true if successful; otherwise returns false.

On Windows service is uninstalled using the system's service control manager.

On Unix service configuration is cleared using QSettings::SystemScope with "QtSoftware" as organization name.

See also install().