qtservicecontroller.html
17.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- qtservice.cpp -->
<head>
<title>QtServiceController Class Reference</title>
<link href="classic.css" rel="stylesheet" type="text/css" />
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top" width="32"><img src="images/qt-logo.png" align="left" width="57" height="67" border="0" /></td>
<td width="1"> </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a></td>
</tr></table><h1 class="title">QtServiceController Class Reference</h1>
<p>The QtServiceController class allows you to control services from separate applications. <a href="#details">More...</a></p>
<pre> #include <QtServiceController></pre><ul>
<li><a href="qtservicecontroller-members.html">List of all members, including inherited members</a></li>
</ul>
<hr />
<a name="public-types"></a>
<h2>Public Types</h2>
<table class="alignedsummary" border="0" cellpadding="0" cellspacing="0" width="100%">
<tr><td class="memItemLeft" align="right" valign="top">enum </td><td class="memItemRight" valign="bottom"><b><a href="qtservicecontroller.html#StartupType-enum">StartupType</a></b> { AutoStartup, ManualStartup }</td></tr>
</table>
<hr />
<a name="public-functions"></a>
<h2>Public Functions</h2>
<table class="alignedsummary" border="0" cellpadding="0" cellspacing="0" width="100%">
<tr><td class="memItemLeft" align="right" valign="top"></td><td class="memItemRight" valign="bottom"><b><a href="qtservicecontroller.html#QtServiceController">QtServiceController</a></b> ( const QString & <i>name</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual </td><td class="memItemRight" valign="bottom"><b><a href="qtservicecontroller.html#dtor.QtServiceController">~QtServiceController</a></b> ()</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><b><a href="qtservicecontroller.html#isInstalled">isInstalled</a></b> () const</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><b><a href="qtservicecontroller.html#isRunning">isRunning</a></b> () const</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><b><a href="qtservicecontroller.html#pause">pause</a></b> ()</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><b><a href="qtservicecontroller.html#resume">resume</a></b> ()</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><b><a href="qtservicecontroller.html#sendCommand">sendCommand</a></b> ( int <i>code</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">QString </td><td class="memItemRight" valign="bottom"><b><a href="qtservicecontroller.html#serviceDescription">serviceDescription</a></b> () const</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">QString </td><td class="memItemRight" valign="bottom"><b><a href="qtservicecontroller.html#serviceFilePath">serviceFilePath</a></b> () const</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">QString </td><td class="memItemRight" valign="bottom"><b><a href="qtservicecontroller.html#serviceName">serviceName</a></b> () const</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><b><a href="qtservicecontroller.html#start">start</a></b> ( const QStringList & <i>arguments</i> )</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><b><a href="qtservicecontroller.html#start-2">start</a></b> ()</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">StartupType </td><td class="memItemRight" valign="bottom"><b><a href="qtservicecontroller.html#startupType">startupType</a></b> () const</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><b><a href="qtservicecontroller.html#stop">stop</a></b> ()</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><b><a href="qtservicecontroller.html#uninstall">uninstall</a></b> ()</td></tr>
</table>
<hr />
<a name="static-public-members"></a>
<h2>Static Public Members</h2>
<table class="alignedsummary" border="0" cellpadding="0" cellspacing="0" width="100%">
<tr><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><b><a href="qtservicecontroller.html#install">install</a></b> ( const QString & <i>serviceFilePath</i>, const QString & <i>account</i> = QString(), const QString & <i>password</i> = QString() )</td></tr>
</table>
<a name="details"></a>
<hr />
<h2>Detailed Description</h2>
<p>The QtServiceController class allows you to control services from separate applications.</p>
<p>QtServiceController provides a collection of functions that lets you install and run a service controlling its execution, as well as query its status.</p>
<p>In order to run a service, the service must be installed in the system's service database using the <a href="qtservicecontroller.html#install">install</a>() function. The system will start the service depending on the specified <a href="qtservicecontroller.html#StartupType-enum">StartupType</a>; it can either be started during system startup, or when a process starts it manually.</p>
<p>Once a service is installed, the service can be run and controlled manually using the <a href="qtservicecontroller.html#start">start</a>(), <a href="qtservicecontroller.html#stop">stop</a>(), <a href="qtservicecontroller.html#pause">pause</a>(), <a href="qtservicecontroller.html#resume">resume</a>() or <a href="qtservicecontroller.html#sendCommand">sendCommand</a>() functions. You can at any time query for the service's status using the <a href="qtservicecontroller.html#isInstalled">isInstalled</a>() and <a href="qtservicecontroller.html#isRunning">isRunning</a>() functions, or you can query its properties using the <a href="qtservicecontroller.html#serviceDescription">serviceDescription</a>(), <a href="qtservicecontroller.html#serviceFilePath">serviceFilePath</a>(), <a href="qtservicecontroller.html#serviceName">serviceName</a>() and <a href="qtservicecontroller.html#startupType">startupType</a>() functions. For example:</p>
<pre> 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();
}</pre>
<p>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.</p>
<p>The QtServiceController destructor neither stops nor uninstalls the associated service. To stop a service the <a href="qtservicecontroller.html#stop">stop</a>() function must be called explicitly. To uninstall a service, you can use the <a href="qtservicecontroller.html#uninstall">uninstall</a>() function.</p>
<p>See also <a href="qtservicebase.html">QtServiceBase</a> and <a href="qtservice.html">QtService</a>.</p>
<hr />
<h2>Member Type Documentation</h2>
<h3 class="fn"><a name="StartupType-enum"></a>enum QtServiceController::StartupType</h3>
<p>This enum describes when a service should be started.</p>
<p><table class="valuelist" border="1" cellpadding="2" cellspacing="1" width="100%">
<tr><th width="25%">Constant</th><th width="15%">Value</th><th width="60%">Description</th></tr>
<tr><td valign="top"><tt>QtServiceController::AutoStartup</tt></td><td align="center" valign="top"><tt>0</tt></td><td valign="top">The service is started during system startup.</td></tr>
<tr><td valign="top"><tt>QtServiceController::ManualStartup</tt></td><td align="center" valign="top"><tt>1</tt></td><td valign="top">The service must be started manually by a process.</td></tr>
</table></p>
<p><b>Warning:</b> The <i>StartupType</i> enum is ignored under UNIX-like systems. A service, or daemon, can only be started manually on such systems with current implementation.</p>
<p>See also <a href="qtservicecontroller.html#startupType">startupType</a>().</p>
<hr />
<h2>Member Function Documentation</h2>
<h3 class="fn"><a name="QtServiceController"></a>QtServiceController::QtServiceController ( const <a href="http://qt.nokia.com/doc/4.6/qstring.html">QString</a> & <i>name</i> )</h3>
<p>Creates a controller object for the service with the given <i>name</i>.</p>
<h3 class="fn"><a name="dtor.QtServiceController"></a>QtServiceController::~QtServiceController () <tt> [virtual]</tt></h3>
<p>Destroys the service controller. This neither stops nor uninstalls the controlled service.</p>
<p>To stop a service the <a href="qtservicecontroller.html#stop">stop</a>() function must be called explicitly. To uninstall a service, you can use the <a href="qtservicecontroller.html#uninstall">uninstall</a>() function.</p>
<p>See also <a href="qtservicecontroller.html#stop">stop</a>() and <a href="qtservicecontroller.html#uninstall">QtServiceController::uninstall</a>().</p>
<h3 class="fn"><a name="install"></a>bool QtServiceController::install ( const <a href="http://qt.nokia.com/doc/4.6/qstring.html">QString</a> & <i>serviceFilePath</i>, const <a href="http://qt.nokia.com/doc/4.6/qstring.html">QString</a> & <i>account</i> = QString(), const <a href="http://qt.nokia.com/doc/4.6/qstring.html">QString</a> & <i>password</i> = QString() ) <tt> [static]</tt></h3>
<p>Installs the service with the given <i>serviceFilePath</i> and returns true if the service is installed successfully; otherwise returns false.</p>
<p>On Windows service is installed in the system's service control manager with the given <i>account</i> and <i>password</i>.</p>
<p>On Unix service configuration is written to <a href="http://qt.nokia.com/doc/4.6/qsettings.html#Scope-enum">QSettings::SystemScope</a> using "QtSoftware" as organization name. <i>account</i> and <i>password</i> arguments are ignored.</p>
<p><b>Warning:</b> 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.</p>
<p>See also <a href="qtservicecontroller.html#uninstall">uninstall</a>() and <a href="qtservicecontroller.html#start">start</a>().</p>
<h3 class="fn"><a name="isInstalled"></a>bool QtServiceController::isInstalled () const</h3>
<p>Returns true if the service is installed; otherwise returns false.</p>
<p>On Windows it uses the system's service control manager.</p>
<p>On Unix it checks configuration written to <a href="http://qt.nokia.com/doc/4.6/qsettings.html#Scope-enum">QSettings::SystemScope</a> using "QtSoftware" as organization name.</p>
<p>See also <a href="qtservicecontroller.html#install">install</a>().</p>
<h3 class="fn"><a name="isRunning"></a>bool QtServiceController::isRunning () const</h3>
<p>Returns true if the service is running; otherwise returns false. A service must be installed before it can be run using a controller.</p>
<p>See also <a href="qtservicecontroller.html#start">start</a>() and <a href="qtservicecontroller.html#isInstalled">isInstalled</a>().</p>
<h3 class="fn"><a name="pause"></a>bool QtServiceController::pause ()</h3>
<p>Requests the running service to pause. If the service's state is <a href="qtservicebase.html#ServiceFlag-enum">QtServiceBase::CanBeSuspended</a>, the service will call the <a href="qtservicebase.html#pause">QtServiceBase::pause</a>() implementation. The function does nothing if the service is not running.</p>
<p>Returns true if a running service was successfully paused; otherwise returns false.</p>
<p>See also <a href="qtservicecontroller.html#resume">resume</a>(), <a href="qtservicebase.html#pause">QtServiceBase::pause</a>(), and <a href="qtservicebase.html#ServiceFlag-enum">QtServiceBase::ServiceFlags</a>.</p>
<h3 class="fn"><a name="resume"></a>bool QtServiceController::resume ()</h3>
<p>Requests the running service to continue. If the service's state is <a href="qtservicebase.html#ServiceFlag-enum">QtServiceBase::CanBeSuspended</a>, the service will call the <a href="qtservicebase.html#resume">QtServiceBase::resume</a>() implementation. This function does nothing if the service is not running.</p>
<p>Returns true if a running service was successfully resumed; otherwise returns false.</p>
<p>See also <a href="qtservicecontroller.html#pause">pause</a>(), <a href="qtservicebase.html#resume">QtServiceBase::resume</a>(), and <a href="qtservicebase.html#ServiceFlag-enum">QtServiceBase::ServiceFlags</a>.</p>
<h3 class="fn"><a name="sendCommand"></a>bool QtServiceController::sendCommand ( int <i>code</i> )</h3>
<p>Sends the user command <i>code</i> to the service. The service will call the <a href="qtservicebase.html#processCommand">QtServiceBase::processCommand</a>() implementation. This function does nothing if the service is not running.</p>
<p>Returns true if the request was sent to a running service; otherwise returns false.</p>
<p>See also <a href="qtservicebase.html#processCommand">QtServiceBase::processCommand</a>().</p>
<h3 class="fn"><a name="serviceDescription"></a><a href="http://qt.nokia.com/doc/4.6/qstring.html">QString</a> QtServiceController::serviceDescription () const</h3>
<p>Returns the description of the controlled service.</p>
<p>See also <a href="qtservicecontroller.html#install">install</a>() and <a href="qtservicecontroller.html#serviceName">serviceName</a>().</p>
<h3 class="fn"><a name="serviceFilePath"></a><a href="http://qt.nokia.com/doc/4.6/qstring.html">QString</a> QtServiceController::serviceFilePath () const</h3>
<p>Returns the file path to the controlled service.</p>
<p>See also <a href="qtservicecontroller.html#install">install</a>() and <a href="qtservicecontroller.html#serviceName">serviceName</a>().</p>
<h3 class="fn"><a name="serviceName"></a><a href="http://qt.nokia.com/doc/4.6/qstring.html">QString</a> QtServiceController::serviceName () const</h3>
<p>Returns the name of the controlled service.</p>
<p>See also <a href="qtservicecontroller.html#QtServiceController">QtServiceController</a>() and <a href="qtservicecontroller.html#serviceDescription">serviceDescription</a>().</p>
<h3 class="fn"><a name="start"></a>bool QtServiceController::start ( const <a href="http://qt.nokia.com/doc/4.6/qstringlist.html">QStringList</a> & <i>arguments</i> )</h3>
<p>Starts the installed service passing the given <i>arguments</i> to the service. A service must be installed before a controller can run it.</p>
<p>Returns true if the service could be started; otherwise returns false.</p>
<p>See also <a href="qtservicecontroller.html#install">install</a>() and <a href="qtservicecontroller.html#stop">stop</a>().</p>
<h3 class="fn"><a name="start-2"></a>bool QtServiceController::start ()</h3>
<p>This is an overloaded function.</p>
<p>Starts the installed service without passing any arguments to the service.</p>
<h3 class="fn"><a name="startupType"></a><a href="qtservicecontroller.html#StartupType-enum">StartupType</a> QtServiceController::startupType () const</h3>
<p>Returns the startup type of the controlled service.</p>
<p>See also <a href="qtservicecontroller.html#install">install</a>() and <a href="qtservicecontroller.html#serviceName">serviceName</a>().</p>
<h3 class="fn"><a name="stop"></a>bool QtServiceController::stop ()</h3>
<p>Requests the running service to stop. The service will call the <a href="qtservicebase.html#stop">QtServiceBase::stop</a>() implementation unless the service's state is <a href="qtservicebase.html#ServiceFlag-enum">QtServiceBase::CannotBeStopped</a>. This function does nothing if the service is not running.</p>
<p>Returns true if a running service was successfully stopped; otherwise false.</p>
<p>See also <a href="qtservicecontroller.html#start">start</a>(), <a href="qtservicebase.html#stop">QtServiceBase::stop</a>(), and <a href="qtservicebase.html#ServiceFlag-enum">QtServiceBase::ServiceFlags</a>.</p>
<h3 class="fn"><a name="uninstall"></a>bool QtServiceController::uninstall ()</h3>
<p>Uninstalls the service and returns true if successful; otherwise returns false.</p>
<p>On Windows service is uninstalled using the system's service control manager.</p>
<p>On Unix service configuration is cleared using <a href="http://qt.nokia.com/doc/4.6/qsettings.html#Scope-enum">QSettings::SystemScope</a> with "QtSoftware" as organization name.</p>
<p>See also <a href="qtservicecontroller.html#install">install</a>().</p>
<p /><address><hr /><div align="center">
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td width="30%" align="left">Copyright © 2010 Nokia Corporation and/or its subsidiary(-ies)</td>
<td width="40%" align="center"><a href="http://qt.nokia.com/doc/trademarks.html">Trademarks</a></td>
<td width="30%" align="right"><div align="right">Qt Solutions</div></td>
</tr></table></div></address></body>
</html>