Introduction to NT Services
At system boot, Windows NT/2K starts an RPC server called as the Service Control Manager (SCM). An NT service is basically a win32 program that is loaded by the SCM. They are loaded before any user has logged into the system. Services may sometimes be manually started instead of getting started automatically at boot time. It was quite recently that I made my first attempt at writing an NT service and I found to my chagrin that very little information was available for a service-newbie. Even on Code Project I could only find wrapper classes which was not what I wanted.
This article gives you a generic service skeleton which you can use as a starting point when you write your first service. The service does nothing basically. I found a couple of examples on the net both of which were called beeper services because that's what they did. They beeped the system speaker at regular intervals. I thought I'd do the same for my skeleton service because that seems to be the easiest way to give an indication that the service is up and running.
Service Skeleton
The main function
I have written my service as a console application and therefore the main function. But I presume there is nothing stopping you from writing your service as a GUI application with a WinMain but since I haven't tried it out yet, I won't delve too much into that. All that the main function does is to call StartServiceCtrlDispatcher
to connect the main thread of our service to the SCM. We simply fill up the SERVICE_TABLE_ENTRY
structure and call StartServiceCtrlDispatcher
passing the SERVICE_TABLE_ENTRY
structure as a parameter.
SERVICE_TABLE_ENTRY servicetable[]=
{
{strServiceName,(LPSERVICE_MAIN_FUNCTION)ServiceMain},
{NULL,NULL}
};
strServiceName
is the name of our service. We also pass a pointer to our ServiceMain
function. I used the name ServiceMain
thinking that, that was mandatory, but later on I realized that you can use any name you want to use. Rather silly of me to think so, I guess. Members of the final entry in the table must have NULL values as an indication that this is the end of the table.
StartServiceCtrlDispatcher(servicetable);
Calling StartServiceCtrlDispatcher
is a straightforward thing as you can see. Simply pass a pointer to a SERVICE_TABLE_ENTRY
array. If StartServiceCtrlDispatcher
fails it returns false immediately, otherwise it will return only after our service has terminated. Very recently I have understood that the same executable can have more than one service, but again since I didn't really try it out, I will refrain from making any bold statements. Anyway I think that one service per exe is a smart way of doing things which follows the keep-it-simple paradigm.
The ServiceMain function
The ServiceMain
is the entry point function for our service. When the SCM starts our service it creates a new thread for executing our ServiceMain
function. The first thing a ServiceMain
does is to call RegisterServiceCtrlHandler
to register a handler function. The service uses this handler function as it's control handler function which receives control codes including codes to start, stop, pause and continue the service.
RegisterServiceCtrlHandler(strServiceName,
(LPHANDLER_FUNCTION)ServiceCtrlHandler);
Once we have registered our service control handler, we need to update the SCM with regard to our service's status. We can do this using the SetServiceStatus
API call. We will need to do this several times during the course of our program and each time it involves filling up a SERVICE_STATUS
structure. Therefore I have written a function called UpdateServiceStatus
which will automate this for us. I discuss this function later on in this article. Basically what we do after registering our handler is to update the SCM with the SERVICE_START_PENDING
status for our service, which means that our service is starting.
UpdateServiceStatus(SERVICE_START_PENDING,NO_ERROR,0,1,3000);
3000 is the dwWaitHint
parameter of the SERVICE_STATUS
structure which is in milliseconds. If this time has expired and the service status has not yet changed, the SCM assumes that an error has occured. Once we have updated the SCM with our status, we create an event. We do this so that we can use WaitForSingleObject
on this event. We can then set the event to terminate our service somewhere else in our program.
killServiceEvent=CreateEvent(0,TRUE,FALSE,0);
After we do this we call UpdateServiceStatus
again with the SERVICE_START_PENDING
status, only this time we increment the dwCheckPoint
parameter of the SERVICE_STATUS
structure. This parameter is used to track the progress of a service during a lengthy start or stop operation. Now we start our service execution thread.
StartServiceThread();
I discuss this function later on, but in summary it simply starts a new thread using CreateThread
where we put our actual functionality. Now we call UpdateServiceStatus
again, passing SERVICE_RUNNING
as our parameter.
UpdateServiceStatus(SERVICE_RUNNING,NO_ERROR,0,0,0);
Well, now that our service is up and running we need to call WaitForSingleObject
on the event we created earlier. Because ServiceMain
should not finish till our service has terminated. Again this is a very simple step as shown below.
WaitForSingleObject(killServiceEvent,INFINITE);
The UpdateServiceStatus function
As I had mentioned earlier, I wrote this function to wrap the SetServiceStatus
API call. It is by no means an innovative idea. Just about every example of a service that I saw on the web used some form of a wrapper function, because during the course of a service program, we need to change the service status several times. Basically what we do in this function is to populate a SERVICE_STATUS
structure. I'll mention some of the members of this structure that are important to us. I strongly suggest that you look up this structure in your copy of MSDN.
dwCurrentState
:- This indicates the current state of the service. Some of the values we use are SERVICE_STOPPED
, SERVICE_RUNNING
and SERVICE_START_PENDING
. You can look up the other allowed values on MSDN.
dwControlsAccepted
:- This is used to indicate the control codes that will be handled by our service handler. For our skeleton service I have used SERVICE_ACCEPT_STOP
and SERVICE_ACCEPT_SHUTDOWN
. These are the only two control codes our skeleton service will handle. When our service is in the SERVICE_START_PENDING
state we must set this parameter to zero.
dwCheckPoint
:- I have mentioned about this parameter earlier. The service increments this value during a lengthy start or stop operation. Any program that invokes an operation on the service can use this value to track the progress of various operations. If you are wondering how a program can do that, take a look at the QueryServiceStatus
API call.
dwWaitHint
:- This specifies the interval in milliseconds before the service status changes again. If the service status has not changed by then, the SCM assumes that an error has occured. Use zero for this parameter when we are setting the service status to SERVICE_RUNNING
.
SetServiceStatus(nServiceStatusHandle,&nServiceStatus);
The first parameter we pass is the service status handle which is returned by the RegisterServiceCtrlHandler
function. I have saved this in a global variable. The second parameter is a pointer to the SERVICE_STATUS
structure that we have populated.
The StartServiceThread function
Well, this function simply starts our service execution thread using the CreateThread
API call. If the thread is created successfully I also set the global nServiceRunning
variable to true. I have used CreateThread
but you might want to use _beginthreadex
if you are planning on using some of the CRT functions in your thread.
The ServiceExecutionThread function
This function is our main service execution thread. In our skeleton service I have simply put a while
loop using my global nServiceRunning
BOOL variable as the while's evaluation expression. Thus till nServiceRunning
is made false the while
loop will loop endlessly. Please keep in mind that an endless while loop will use up your CPU infinitely till your machine crawls to a pathetic frozen state. I am avoiding this using a Sleep
, but you might want to use some kind of blocking calls or waiting calls in your programs.
while(nServiceRunning)
{
Beep(450,150);
Sleep(4000);
}
Well, that's the service body for you. It won't get any simpler than that I guess. Of course the functionality is useless, that's why we call it a skeleton service.
The ServiceCtrlHandler function
This is our service's control handler function. All service control requests like starting a service, stopping a service etc. are handled by the control handler. The MSDN prototype for this function is as follows.
VOID WINAPI Handler(
DWORD fdwControl );
Basically we put a switch statement on the fdwControl
variable and we have case blocks for each control code that we intend to handle.
switch(nControlCode)
{
case SERVICE_CONTROL_SHUTDOWN:
case SERVICE_CONTROL_STOP:
nServiceCurrentStatus=SERVICE_STOP_PENDING;
success=UpdateServiceStatus(SERVICE_STOP_PENDING,NO_ERROR,0,1,3000);
KillService();
return;
default:
break;
}
As you can see our skeleton program's switch construct handles only two control codes, SERVICE_CONTROL_SHUTDOWN
and SERVICE_CONTROL_STOP
. If you scroll up, you'll see that when I set the service status to SERVICE_RUNNING
I set the dwControlsAccepted
member of the SERVICE_STATUS
structure to SERVICE_ACCEPT_STOP|SERVICE_ACCEPT_SHUTDOWN
. Thus these are the only two control codes that the SCM will send to our control handler function. As you can see, for both cases, we are using the same code. All we do is to change our global service status variable to SERVICE_STOP_PENDING
and then we call UpdateServiceStatus
passing SERVICE_STOP_PENDING
. Then we call our own KillService
function (which I explain down below) and return.
The KillService function
Well, we use the KillService
function to terminate our service. We first set nServiceRunning to false, so that our service execution thread exits. Then we set our blocking event so that ServiceMain
will exit.
nServiceRunning=false;
SetEvent(killServiceEvent);
Once we have done that we need to inform the SCM that our service has terminated. So we call UpdateServiceStatus
passing SERVICE_STOPPED
as the dwCurrentState
parameter.
UpdateServiceStatus(SERVICE_STOPPED,NO_ERROR,0,0,0);
Installing our service
First we use the API call OpenSCManager
to get a handle to the SCM database.
scm=OpenSCManager(0,0,SC_MANAGER_CREATE_SERVICE);
We pass 0 for both lpMachineName and lpDatabaseName as we need to open the SCM database on the local machine. We pass SC_MANAGER_CREATE_SERVICE
as our dwDesiredAccess
so that we can use the CreateService
API call to create our new service and add it to the SCM database.
CreateService(scm,"NishService",
"Buster's first NT service",
SERVICE_ALL_ACCESS,SERVICE_WIN32_OWN_PROCESS,SERVICE_DEMAND_START,
SERVICE_ERROR_NORMAL,
"D:\\nish\\FirstService\\Debug\\FirstService.exe",
0,0,0,0,0);
You must look up CreateService
on MSDN. I have used SERVICE_ALL_ACCESS
as my dwDesiredAccess
parameter. This allows me full rights and I can do as I please. I have used SERVICE_DEMAND_START
as the dwStartType
parameter. This means the service won't start automatically at system boot time. It will need to be manually started either via the control-panel's Component Services applet or programmatically using StartService
. Later on in this article I show you how to programmatically start and stop our service. You need to specify the full path of the service executable. The last 5 parameters can be ignored for now. To be frank, as soon as I found that they can all be NULL, I didn't bother to interpret their purpose. But I suggest that you go ahead and figure out how you can put them to proper use.
Starting our service programmatically
The first thing we need to do is to use OpenSCManager
to obtain a handle to the SCM. Now we use OpenService
to obtain a handle to our skeleton service.
NishService=OpenService(scm,"NishService",SERVICE_ALL_ACCESS);
If OpenService
successfully returns,( which we can figure out by checking whether it has returned NULL, in which case the call has failed), we can proceed by calling StartService
using the handle returned by OpenService
.
StartService(NishService,0,NULL);
Since we are not passing any parameters to ServiceMain
, I am passing 0 and NULL as the 2nd and 3rd parameters. If StartService
succeeds, the return value is nonzero and we can assume that our service has been successfully started. This will become obvious soon, when the PC speaker starts beeping once in 4 seconds and you might get rude stares from your co-employees. In which case you might want to stop the service.
Stopping our service programmatically
The first two steps for stopping our service are same as for starting our service. We call OpenSCManager
to get a handle to the SCM and then call OpenService
to get a handle to our service. Now we can use the ControlService
API call to send a control code to our service handler.
ControlService(NishService,SERVICE_CONTROL_STOP,&m_SERVICE_STATUS);
m_SERVICE_STATUS
is a SERVICE_STATUS
structure which will receive status information about our service. As you can see I have passed SERVICE_CONTROL_STOP
as the control code. And we know how we have handled this control code in our service handler. Now it all begins to fit into a pattern, huh? By now the 4-second beeping will have stopped and the rude stares will slowly fade away.
Thank You [and remember that I am a service-newbie too]