File: Poco.Util.ServerApplication.html

package info (click to toggle)
poco-doc 1.3.6-1
  • links: PTS
  • area: main
  • in suites: buster, jessie, jessie-kfreebsd, squeeze, stretch, wheezy
  • size: 10,076 kB
  • ctags: 9,611
  • sloc: makefile: 31
file content (133 lines) | stat: -rw-r--r-- 14,360 bytes parent folder | download | duplicates (2)
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
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Class Poco::Util::ServerApplication</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<meta name="author" content="Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="publisher" content="Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="copyright" content="Copyright (c) 2009, Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="language" content="en"/>
<meta name="date" content="2009-11-24"/>
<meta name="generator" content="PocoDoc"/>
<link rel="stylesheet" href="css/styles.css" type="text/css"/>
</head>
<body bgcolor="#ffffff" leftmargin="0" topmargin="0">
<div class="header">
<h1 class="namespace"><a href="Poco.Util.html" class="namespace">Poco::Util</a></h1>
<h1 class="symbol">class ServerApplication</h1>
</div>
<div class="body">
<p>
<b>Library:</b> Util<br />
<b>Package:</b> Application<br />
<b>Header:</b> Poco/Util/ServerApplication.h</p>
<h2>Description</h2>
<div class="description">
<p>A subclass of the <a href="Poco.Util.Application.html" title="class Poco::Util::Application">Application</a> class that is used for implementing server applications. </p>
<p>A <a href="Poco.Util.ServerApplication.html" title="class Poco::Util::ServerApplication">ServerApplication</a> allows for the application to run as a Windows service or as a Unix daemon without the need to add extra code. </p>
<p>For a <a href="Poco.Util.ServerApplication.html" title="class Poco::Util::ServerApplication">ServerApplication</a> to work both from the command line and as a daemon or service, a few rules must be met: </p>
<ul>
<li>Subsystems must be registered in the constructor. </li>
<li>All non-trivial initializations must be made in the initialize() method. </li>
<li>At the end of the main() method, <a href="Poco.Util.ServerApplication.html#17209" title="Poco::Util::ServerApplication::waitForTerminationRequest()">waitForTerminationRequest</a>() should be called. </li>
<li>The main(argc, argv) function must look as follows: </li>
</ul>
<p></p>
<pre>int main(int argc, char** argv)
{
    MyServerApplication app;
    return app.run(argc, argv);
}
</pre>
<p>The POCO_SERVER_MAIN macro can be used to implement main(argc, argv). If POCO has been built with POCO_WIN32_UTF8, POCO_SERVER_MAIN supports <a href="Poco.Unicode.html" title="class Poco::Unicode">Unicode</a> command line arguments. </p>
<p>On Windows platforms, an application built on top of the <a href="Poco.Util.ServerApplication.html" title="class Poco::Util::ServerApplication">ServerApplication</a> class can be run both from the command line or as a service. </p>
<p>To run an application as a Windows service, it must be registered with the Windows Service Control Manager (SCM). To do this, the application can be started from the command line, with the /registerService option specified. This causes the application to register itself with the SCM, and then exit. Similarly, an application registered as a service can be unregistered, by specifying the /unregisterService option. The file name of the application executable (excluding the .exe suffix) is used as the service name. Additionally, a more user-friendly name can be specified, using the /displayName option (e.g., /displayName=&quot;Demo Service&quot;). </p>
<p>An application can determine whether it is running as a service by checking for the &quot;application.runAsService&quot; configuration property. </p>
<p></p>
<pre>if (config().getBool(&quot;application.runAsService&quot;, false))
{
    // do service specific things
}
</pre>
<p>Note that the working directory for an application running as a service is the Windows system directory (e.g., C:\Windows\system32). Take this into account when working with relative filesystem paths. Also, services run under a different user account, so an application that works when started from the command line may fail to run as a service if it depends on a certain environment (e.g., the PATH environment variable). </p>
<p>An application registered as a Windows service can be started with the NET START &lt;name&gt; command and stopped with the NET STOP &lt;name&gt; command. Alternatively, the Services MMC applet can be used. </p>
<p>On Unix platforms, an application built on top of the <a href="Poco.Util.ServerApplication.html" title="class Poco::Util::ServerApplication">ServerApplication</a> class can be optionally run as a daemon by giving the &mdash;daemon command line option. A daemon, when launched, immediately forks off a background process that does the actual work. After launching the background process, the foreground process exits. </p>
<p>After the initialization is complete, but before entering the main() method, the current working directory for the daemon process is changed to the root directory (&quot;/&quot;), as it is common practice for daemon processes. Therefore, be careful when working with files, as relative paths may not point to where you expect them point to. </p>
<p>An application can determine whether it is running as a daemon by checking for the &quot;application.runAsDaemon&quot; configuration property. </p>
<p></p>
<pre>if (config().getBool(&quot;application.runAsDaemon&quot;, false))
{
    // do daemon specific things
}
</pre>
<p>When running as a daemon, specifying the &mdash;pidfile option (e.g., &mdash;pidfile=/var/run/sample.pid) may be useful to record the process ID of  the daemon in a file. The PID file will be removed when the daemon process  terminates (but not, if it crashes). </p>
</div>
<h2>Inheritance</h2>
<p><b>Direct Base Classes: </b><a href="Poco.Util.Application.html" title="class Poco::Util::Application">Application</a></p>
<p><b>All Base Classes: </b><a href="Poco.RefCountedObject.html" title="class Poco::RefCountedObject">Poco::RefCountedObject</a>, <a href="Poco.Util.Application.html" title="class Poco::Util::Application">Application</a>, <a href="Poco.Util.Subsystem.html" title="class Poco::Util::Subsystem">Subsystem</a></p>
<h2>Member Summary</h2>
<p><b>Member Functions: </b><a href="Poco.Util.ServerApplication.html#17210" title="Poco::Util::ServerApplication::defineOptions()">defineOptions</a>, <a href="Poco.Util.ServerApplication.html#17212" title="Poco::Util::ServerApplication::handleOption()">handleOption</a>, <a href="Poco.Util.ServerApplication.html#17201" title="Poco::Util::ServerApplication::isInteractive()">isInteractive</a>, <a href="Poco.Util.ServerApplication.html#17202" title="Poco::Util::ServerApplication::run()">run</a>, <a href="Poco.Util.ServerApplication.html#17215" title="Poco::Util::ServerApplication::terminate()">terminate</a>, <a href="Poco.Util.ServerApplication.html#17209" title="Poco::Util::ServerApplication::waitForTerminationRequest()">waitForTerminationRequest</a></p>
<p><b>Inherited Functions: </b><a href="Poco.Util.Application.html#16424" title="Poco::Util::Application::addSubsystem()">addSubsystem</a>, <a href="Poco.Util.Application.html#16444" title="Poco::Util::Application::commandName()">commandName</a>, <a href="Poco.Util.Application.html#16445" title="Poco::Util::Application::config()">config</a>, <a href="Poco.Util.Application.html#16458" title="Poco::Util::Application::defineOptions()">defineOptions</a>, <a href="Poco.RefCountedObject.html#9659" title="Poco::RefCountedObject::duplicate()">duplicate</a>, <a href="Poco.Util.Application.html#16467" title="Poco::Util::Application::findFile()">findFile</a>, <a href="Poco.Util.Application.html#16442" title="Poco::Util::Application::getSubsystem()">getSubsystem</a>, <a href="Poco.Util.Application.html#16460" title="Poco::Util::Application::handleOption()">handleOption</a>, <a href="Poco.Util.Application.html#16426" title="Poco::Util::Application::init()">init</a>, <a href="Poco.Util.Application.html#16453" title="Poco::Util::Application::initialize()">initialize</a>, <a href="Poco.Util.Application.html#16434" title="Poco::Util::Application::initialized()">initialized</a>, <a href="Poco.Util.Application.html#16448" title="Poco::Util::Application::instance()">instance</a>, <a href="Poco.Util.Application.html#16437" title="Poco::Util::Application::loadConfiguration()">loadConfiguration</a>, <a href="Poco.Util.Application.html#16446" title="Poco::Util::Application::logger()">logger</a>, <a href="Poco.Util.Application.html#16465" title="Poco::Util::Application::main()">main</a>, <a href="Poco.Util.Application.html#16452" title="Poco::Util::Application::name()">name</a>, <a href="Poco.Util.Application.html#16447" title="Poco::Util::Application::options()">options</a>, <a href="Poco.RefCountedObject.html#9661" title="Poco::RefCountedObject::referenceCount()">referenceCount</a>, <a href="Poco.Util.Application.html#16456" title="Poco::Util::Application::reinitialize()">reinitialize</a>, <a href="Poco.RefCountedObject.html#9660" title="Poco::RefCountedObject::release()">release</a>, <a href="Poco.Util.Application.html#16443" title="Poco::Util::Application::run()">run</a>, <a href="Poco.Util.Application.html#16463" title="Poco::Util::Application::setLogger()">setLogger</a>, <a href="Poco.Util.Application.html#16435" title="Poco::Util::Application::setUnixOptions()">setUnixOptions</a>, <a href="Poco.Util.Application.html#16449" title="Poco::Util::Application::startTime()">startTime</a>, <a href="Poco.Util.Application.html#16451" title="Poco::Util::Application::stopOptionsProcessing()">stopOptionsProcessing</a>, <a href="Poco.Util.Application.html#16455" title="Poco::Util::Application::uninitialize()">uninitialize</a>, <a href="Poco.Util.Application.html#16450" title="Poco::Util::Application::uptime()">uptime</a></p>
<h2>Constructors</h2>
<h3><a name="17199">ServerApplication</a></h3>
<p class="decl"><a href="Poco.Util.ServerApplication.html" title="class Poco::Util::ServerApplication">ServerApplication</a>();</p>
<div class="description">
<p>Creates the <a href="Poco.Util.ServerApplication.html" title="class Poco::Util::ServerApplication">ServerApplication</a>. </p>
</div>
<h2>Destructor</h2>
<h3><a name="17200">~ServerApplication</a> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">~<a href="Poco.Util.ServerApplication.html" title="class Poco::Util::ServerApplication">ServerApplication</a>();</p>
<div class="description">
<p>Destroys the <a href="Poco.Util.ServerApplication.html" title="class Poco::Util::ServerApplication">ServerApplication</a>. </p>
</div>
<h2>Member Functions</h2>
<h3><a name="17201">isInteractive</a></h3>
<p class="decl">bool isInteractive() const;</p>
<div class="description">
<p>Returns true if the application runs from the command line. Returns false if the application runs as a Unix daemon or Windows service. </p>
</div>
<h3><a name="17202">run</a></h3>
<p class="decl">int run(<br />&nbsp;&nbsp;&nbsp;&nbsp;int argc,<br />&nbsp;&nbsp;&nbsp;&nbsp;char * * argv<br />);</p>
<div class="description">
<p>Runs the application by performing additional initializations and calling the main() method. </p>
</div>
<h3><a name="17205">run</a></h3>
<p class="decl">int run(<br />&nbsp;&nbsp;&nbsp;&nbsp;int argc,<br />&nbsp;&nbsp;&nbsp;&nbsp;wchar_t * * argv<br />);</p>
<div class="description">
<p>Runs the application by performing additional initializations and calling the main() method. </p>
<p>This Windows-specific version of init is used for passing <a href="Poco.Unicode.html" title="class Poco::Unicode">Unicode</a> command line arguments from wmain(). </p>
</div>
<h3><a name="17210">defineOptions</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" />  <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void defineOptions(<br />&nbsp;&nbsp;&nbsp;&nbsp;<a href="Poco.Util.OptionSet.html" title="class Poco::Util::OptionSet">OptionSet</a> &amp; options<br />);</p>
<div class="description">
<p></p>
</div>
<div class="description"><p><b>See also:</b> <a href="Poco.Util.Application.html#16458" title="Poco::Util::Application::defineOptions()">Poco::Util::Application::defineOptions()</a></p></div>
<h3><a name="17212">handleOption</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" />  <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void handleOption(<br />&nbsp;&nbsp;&nbsp;&nbsp;const std::string &amp; name,<br />&nbsp;&nbsp;&nbsp;&nbsp;const std::string &amp; value<br />);</p>
<div class="description">
<p></p>
</div>
<div class="description"><p><b>See also:</b> <a href="Poco.Util.Application.html#16460" title="Poco::Util::Application::handleOption()">Poco::Util::Application::handleOption()</a></p></div>
<h3><a name="17208">run</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" />  <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">int run();</p>
<div class="description">
<p></p>
</div>
<div class="description"><p><b>See also:</b> <a href="Poco.Util.Application.html#16443" title="Poco::Util::Application::run()">Poco::Util::Application::run()</a></p></div>
<h3><a name="17215">terminate</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" />  <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">static void terminate();</p>
<div class="description">
<p></p>
</div>
<h3><a name="17209">waitForTerminationRequest</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> </h3>
<p class="decl">void waitForTerminationRequest();</p>
<div class="description">
<p></p>
</div>
<p class="footer">POCO C++ Libraries 1.3.6-all<br />
Copyright &copy; 2009, <a href="http://pocoproject.org/" target="_blank">Applied Informatics Software Engineering GmbH and Contributors</a></p>

</div>
</body>
</html>