libcommonc++
0.7
|
Basic functionality for a system service, such as a daemon on UNIX or an "NT Service" on Windows. More...
#include <Service.h++>
Public Member Functions | |
Service (int argc, char **argv, const String &version, const String &compileDate="", const String &compileTime="") | |
Construct a new Service. More... | |
virtual | ~Service () |
Destructor. More... | |
Protected Member Functions | |
void | setDescription (const String &desc) |
Set the service description. More... | |
void | setWorkingDir (const String &dir) |
On POSIX systems, set the working directory for the service daemon process. More... | |
virtual bool | processOption (char opt, const String &longOpt, const String &arg=String::null) |
Process a command-line option. More... | |
void | detach () |
Detach the process from the console. More... | |
virtual void | run ()=0 |
The body of the service. More... | |
void | testShutdown () |
Test for asynchronous termination requests. More... | |
virtual void | shutdown ()=0 |
Shutdown handler. More... | |
bool | isDebug () const |
Test if debug (foreground) mode is enabled. More... | |
bool | registerOption (char opt, const String &longOpt, const String &argName, const String &desc) |
Register a command-line option. More... | |
bool | parseOptions (int argc, char **argv, int &index) |
Parse the command line options. More... | |
virtual void | printUsage () |
Print the usage text. More... | |
void | printError (const char *message,...) |
Print an error message. More... | |
Basic functionality for a system service, such as a daemon on UNIX or an "NT Service" on Windows.
On POSIX systems, the service recognizes the –pidfile
command line switch, whose argument is the path of a file to which the daemon process's PID should be written.
On Windows, the service recognizes the following command line switches:
–name
=name –displayname
=name –desc
=description –install
–uninstall
–start
–stop
On all systems, the following switch is recognized:
–debug
This class is implicitly a singleton; there can be only one instantiation of the class per process. The class should be subclassed and instantiated within the program's main() function.
Service | ( | int | argc, |
char ** | argv, | ||
const String & | version, | ||
const String & | compileDate = "" , |
||
const String & | compileTime = "" |
||
) |
Construct a new Service.
argc | The argument count (from main()). |
argv | The argument list (from main()). |
version | The optional version of the program; if not supplied, it defaults to "0.0". |
compileDate | The optional compile date of the program; typically provided by the compiler-defined macro __DATE__. |
compileTime | The optional compile time of the program; typically provided by the compiler-defined macro __TIME__. |
|
virtual |
Destructor.
|
protected |
Detach the process from the console.
This method must be called from the constructor once command line option processing and any other necessary initialization is complete. On POSIX systems, it forks a daemon process, while on Windows it passes control to the Service Control Manager (SCM) subsystem. On all platforms, execution resumes in the run() method, where the body of the service must be implemented.
SystemException | If the detach operation fails. |
|
inlineprotected |
Test if debug (foreground) mode is enabled.
|
protectedinherited |
Parse the command line options.
This method should be called from the constructor at the appropriate time, after any application-specific options have been registered and any other necessary initialization has been completed.
argc | The argument count. |
argv | The argument list. |
index | Upon return, the index of the first non-option argument. |
|
protectedinherited |
Print an error message.
The program name is automatically prepended to the message.
|
protectedvirtualinherited |
Print the usage text.
|
protectedvirtual |
Process a command-line option.
This method is called for each registered option that is encountered on the command line during the call to parseOptions().
The Application class registers the "--help" and "--version" command line options automatically. Therefore a subclass should override processOption() such that if it does not recognize the option, it will call Application::processOption() to give it a chance to process it.
opt | The one-character switch, or NUL if not applicable. |
longOpt | The long name for the switch, or String::null if not applicable. |
arg | The argument for the switch, or NULL if not applicable. |
Reimplemented from Application.
|
protectedinherited |
Register a command-line option.
The option may have a short (one character) form and/or a long form. A typical invocation might look like this:
registerOption('o', "output", "file", "Specify @@ as the output file.");
The corresponding usage help text for this switch would appear as:
-o <file> --output=<file> - Specify <file> as the output file.
opt | The one-character switch (e.g., 'v' for "-v"), or NUL if not applicable. |
longOpt | The long name for the switch (e.g., "verbose" for "--verbose"), or String::null if not applicable. |
argName | A token describing the argument for the switch, or the empty string "" if the switch does not accept an argument. |
desc | The description of the option, used in generating the usage text. Any occurrence of the token "@@" within the description will be replaced with a stylized form of the argument name, either by underlining the token or by enclosing it within angle brackets. |
|
protectedpure virtual |
The body of the service.
This method must be implemented to provide the actual service processing loop. It must periodically call testShutdown() to ensure that an asynchronous shutdown request will be processed in a timely manner.
|
inlineprotected |
Set the service description.
On Windows, this is used for the description in the Service Manager applet when the service is installed; on other platforms, it serves no purpose.
desc | The new description. |
|
inlineprotected |
On POSIX systems, set the working directory for the service daemon process.
The default working directory is the root directory ("/").
dir | The working directory. |
|
protectedpure virtual |
Shutdown handler.
The method must be overriden to provide cleanup and shutdown logic for the service. It is invoked as a side effect of calling testShutdown() when the service has been stopped via a TERM signal (UNIX), the Service Manager applet (Windows), or through use of the "--stop" command line switch (Windows). This function should not call exit()
or otherwise terminate the process.
Reimplemented from Application.
|
protected |
Test for asynchronous termination requests.
The service must regularly call this method to check for termination requests. The method will delegate to shutdown() if it has determined that a termination request is pending.