TService - A Windows NT Service Class

Version: 1.02
Written by: Christopher Kohlhoff (chris at tenermerx dot com)
Last updated: 22 February 1998

View Header File
Download Code
View Example 1
View Example 2

Overview

TService is a class that encapsulates most of the work needed to implement a Win32 service. At a minimum you have to override just 3 functions from the TService class, only one of which performs the "work" of the service. This simplicity is especially useful when porting UNIX daemons or other console applications to run as services. TService also provides functions for installing and removing the service, and includes a basic wrapper around the event log API (since this is normally the only way a service can communicate with the user).

Using TService

• The TService class is abstract, so to use it you must derive a new class and implement the methods GetName, GetDisplayName and Run.

• To register and run the service, TService provides the methods Register, Unregister and Start. You would typically call these methods from the "main" function.

• To allow for easy debugging, TService has two versions of the Start method. The version which takes two arguments (argc and argv) runs the program in console mode so that you can debug it.

• When inside the Run method, your code must regularly call the CheckStop method. This will return true when the user has chosen to halt your service (in which case you must return as soon as possible). CheckStop will block when the user has paused your service, and release when the user selects continue.

• To perform initialisation and cleanup, override the Init and Cleanup methods respectively. If the Init method is likely to take a long time (say more than 10 seconds) then you should delay the time-consuming work until the Run method. For Init functions which take up to 10 seconds you should call SetStatus with the value SERVICE_START_PENDING every so often to let the system know that your service is still starting up. By returning false from the Init method, you are indicating that your service has failed to start. TService will tell Windows that your service has stopped with a specific error code of -1. To use a different error code call the SetStatus method yourself before returning from Init (see below).

• To write a message to the event log, use the Log method. This takes two arguments: a string to be written to the log, and a severity (Error, Warning and Info).

• To indicate that your service is halting due to an error, you should call the SetStatus method. The first parameter should be SERVICE_STOPPED, and the second parameter is a non-zero error code (which you may define).

• To execute code when the service is being paused or continued by the user override the PauseBegin and PauseEnd methods respectively.

• If you need to use OWL classes from your service, change the target to be a Windows GUI application using OWL, and change "main" to be "OwlMain". The supplied examples are not linked to OWL to save on the overhead. TService does require Borland's "Class Library".

Examples

• MINSVC.CPP demonstrates the smallest (and least useful) service that can be written using the TService class. It shows how the GetName, GetDisplayName, and Run methods should be overridden, and it demonstrates how to register and run your service from the "main" function.

• DAYTIME.CPP shows how to write a Winsock server (in this case, a "daytime" server) using TService. It shows how to override the Init, Cleanup, PauseBegin and PauseEnd functions, and it shows how to use the Log function to write messages to the event log.

Changes