libcommonc++  0.7
Service Class Referenceabstract

Basic functionality for a system service, such as a daemon on UNIX or an "NT Service" on Windows. More...

#include <Service.h++>

Inheritance diagram for Service:
Collaboration diagram for Service:

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...
 

Detailed Description

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
Specifies the name of the service; this is the logical name by which the service is known to Windows.
–displayname=name
Specifies the display name of the service; this is the name by which the service is known to the Service Control Manager (SCM), and appears in the "Name" column in the Service Manager applet.
–desc=description
Specifies a brief description for the service; this description appears in the "Description" column in the Service Manager applet.
–install
Installs the service into the Service Control Manager.
–uninstall
Uninstalls the service from the Service Control Manager.
–start
Starts the service.
–stop
Stops the service.

On all systems, the following switch is recognized:

–debug
Indicates that the service should run in debug (foreground) mode. In this mode, the detach() function passes control directly to the run() function without first detaching from the console. In addition, a keyboard interrupt (typically Control-C) will cause a termination request.

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.

Author
Mark Lindner

Constructor & Destructor Documentation

◆ Service()

Service ( int  argc,
char **  argv,
const String version,
const String compileDate = "",
const String compileTime = "" 
)

Construct a new Service.

Parameters
argcThe argument count (from main()).
argvThe argument list (from main()).
versionThe optional version of the program; if not supplied, it defaults to "0.0".
compileDateThe optional compile date of the program; typically provided by the compiler-defined macro __DATE__.
compileTimeThe optional compile time of the program; typically provided by the compiler-defined macro __TIME__.

◆ ~Service()

~Service ( )
virtual

Destructor.

Member Function Documentation

◆ detach()

void detach ( )
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.

Exceptions
SystemExceptionIf the detach operation fails.

◆ isDebug()

bool isDebug ( ) const
inlineprotected

Test if debug (foreground) mode is enabled.

◆ parseOptions()

bool parseOptions ( int  argc,
char **  argv,
int &  index 
)
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.

Parameters
argcThe argument count.
argvThe argument list.
indexUpon return, the index of the first non-option argument.
Returns
true if the options were parsed successfully, or false if there was a parsing error. (Parsing errors are reported to stderr as a side-effect.)

◆ printError()

void printError ( const char *  message,
  ... 
)
protectedinherited

Print an error message.

The program name is automatically prepended to the message.

◆ printUsage()

void printUsage ( )
protectedvirtualinherited

Print the usage text.

◆ processOption()

bool processOption ( char  opt,
const String longOpt,
const String arg = String::null 
)
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.

Parameters
optThe one-character switch, or NUL if not applicable.
longOptThe long name for the switch, or String::null if not applicable.
argThe argument for the switch, or NULL if not applicable.
Returns
true if the option was processed successfully, false otherwise.

Reimplemented from Application.

◆ registerOption()

bool registerOption ( char  opt,
const String longOpt,
const String argName,
const String desc 
)
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.
Parameters
optThe one-character switch (e.g., 'v' for "-v"), or NUL if not applicable.
longOptThe long name for the switch (e.g., "verbose" for "--verbose"), or String::null if not applicable.
argNameA token describing the argument for the switch, or the empty string "" if the switch does not accept an argument.
descThe 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.
Returns
true if the option was registered successfully, false otherwise. Attempts to register an existing option will fail.

◆ run()

virtual void run ( )
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.

◆ setDescription()

void setDescription ( const String desc)
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.

Parameters
descThe new description.

◆ setWorkingDir()

void setWorkingDir ( const String dir)
inlineprotected

On POSIX systems, set the working directory for the service daemon process.

The default working directory is the root directory ("/").

Parameters
dirThe working directory.

◆ shutdown()

virtual void shutdown ( )
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.

◆ testShutdown()

void testShutdown ( )
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.


The documentation for this class was generated from the following files: