| Home | |
The QtService class provides an API from implementing Windows services and Unix daemons. More...
#include <qtservice.h>
A Windows service or Unix daemon (a "service"), is a program that runs regardless of whether a user is logged in or not. Services are usually non-interactive console applications, but can also provide a user interface.
A service is installed in a system's service database with install(). The system will start the service on startup, depending on the StartupType specified. A service can also be started explicitly with exec().
On Windows 95, 98 and ME the service is registered in the Windows Registry's RunServices entry.
On Windows NT based systems, such as Windows NT 4, 2000, and XP, the 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 the service is implemented as a daemon.
When a service is started, it calls initialize(), and then the run() implementation which usually creates a QApplication object and enters the event loop. The stop() implementation must make the application leave the event loop, so that the run() implementation can return; usually this is done by calling qApp->quit().
On Windows NT based systems the service control manager can send commands to the service to pause(), resume(), or stop() the service, as well as service specific user() commands. This can be achieved on other systems by running the executable itself with suitable command line arguments.
A service can report events to the system's event log with reportEvent(). The status of the service can be queried with isInstalled() and isRunning().
A running service can be stopped by the service control manager, or by calling terminate(). If the service is no longer needed it can be uninstalled from the system's service database with uninstall().
The implementation of a service application's main() entry point function usually creates a QtService object, calls parseArguments(), and returns the result of that call.
When a service object is destroyed the service is not stopped and is not uninstalled.
Warning: On Windows, different versions have different limitations as to what a service is allowed to do. For example, on Windows XP Home Edition the Local System Account does not have the privilege to "Logon as a service". If you have problems with a service consult the documentation provided by Microsoft, i.e. in MSDN.
This enum describes the different types of events reported by a service to the system log.
This enum describes when a service should be started.
There can only be one QtService object in a process.
The service is not installed or started. The name must not contain any backslashes, cannot be longer than 255 characters, and must be unique in the system's service database.
See also install() and exec().
See also uninstall().
Tries to start the service, passing argc and argv to the run() implementation.
If the service is installed it is started as a separate process, and exec() returns immediately with the return value 0 if the service could be started. Otherwise a non-zero error code is returned and an error event is reported to the system's event log.
If the service is not installed the run() implementation is called directly, and the result is returned.
The default implementation of parseArguments() calls this function when the command line option -e (or -exec) is used.
See also install(), start(), and run().
The default implementation does nothing and returns true.
See also run().
Installs the service in the system's service control manager and returns true if successful; otherwise returns false.
The service reports the result of the installation to the system's event log.
The default implementation of parseArguments() calls this function when the command line option -i (or -install) is used.
Warning: Due to the different implementations of how services (daemons) are installed on various UNIX-like systems, this function is not implemented on such systems.
See also uninstall().
Returns true if the service is installed in the system's default service control manager; otherwise returns false.
Warning: This function always returns false on UNIX-like systems.
See also install().
Returns true if the service is running; otherwise returns false.
A service must be installed before it can be run, except on UNIX-like systems; see install().
Note that isRunning() returns false if the program runs stand-alone, so you can modify your application's behavior depending on the context it is running in:
int MyService::run( int argc, char **argv )
{
QApplication app( argc, argv );
QWidget *gui = new ServiceGui( ... );
if ( !isRunning() ) // running stand alone -> quit when GUI is closed
app.setMainWidget( gui );
gui->show();
return app.exec();
}
See also isInstalled(), exec(), start(), and stop().
The following arguments are recognized:
| Short | Long | Explanation |
|---|---|---|
| -i | -install | Calls install() to install the service |
| -u | -uninstall | Calls uninstall() to uninstall the service |
| -e | -exec | Calls exec() to execute the service application |
| -t | -terminate | Calls terminate() to stop the service application |
| -p | -pause | Call requestPause() to pause the service application |
| -r | -resume | Call requestResume() to resume a paused service application |
| -c cmd | -command cmd | Send the user defined command code cmd to the service application |
| -v | -version | Displays version and status information |
If no argument is provided the service calls start() to run the service and listen to commands from the service control manager.
Examples: interactive/main.cpp and server/main.cpp.
The default implementation does nothing.
See also resume() and requestPause().
Example: interactive/main.cpp.
Report an event of type type with text message to the local system event log. The event identifier ID and the event category category are user defined values. data 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.
Requests the running service to pause. The service will call the pause() implementation.
This function does nothing if the service is not running.
See also requestResume().
Requests a paused service to continue. The service will call the resume() implementation.
This function does nothing if the service is not running.
See also requestPause().
The default implementation does nothing.
See also pause() and requestResume().
Example: interactive/main.cpp.
This pure virtual function must be implemented in derived classes in order to perform the service's work. Usually you create the QtService subclass instance in main() and return the value of a call to parseArguments(). In the subclass's run() function you create the QApplication object passing argc and argv, initialize the application, and enter the event loop (e.g. by calling return app.event(); in this function.
See also start(), exec(), terminate(), and stop().
Example: interactive/main.cpp.
Sends the user command code to the service. The service will call the user() implementation.
This function does nothing if the service is not running.
See also serviceName().
See also serviceDescription().
Starts the service, and returns true if successful; otherwise returns false.
A service must be installed before it can be started, except on UNIX-like systems; see install().
The service reports an error EventType to the system event log if starting the service fails.
The default implementation of parseArguments() calls this function if no command line options are used.
See also install(), exec(), stop(), and isRunning().
See also StartupType.
See also run() and terminate().
Asks the service control manager to stop the service if the service is running, otherwise does nothing. Returns true if the service could be stopped (or was not running); otherwise returns false.
The default implementation of parseArguments() calls this function when the command line option -t (or -terminate) is used.
See also exec() and isRunning().
Uninstalls the service from the system's default service control manager and returns true if successful; otherwise returns false.
The service reports the result of the uninstallation to the system's event log.
The default implementation of parseArguments() calls this function when the command line option -u (or -uninstall) is used.
Warning: Due to the different implementations of how services (daemons) are installed on various UNIX-like systems, this function is not implemented on such systems.
See also install() and isInstalled().
The default implementation does nothing.
See also sendCommand().
Example: interactive/main.cpp.
This file is part of the Qt Solutions.
Copyright © 2003-2005
Trolltech. All Rights Reserved.
| Copyright © 2003-2005 Trolltech | Trademarks | Qt Solutions
|