Coding Windows Services in C++

Warning! Some information on this page is older than 5 years now. I keep it for reference, but it probably doesn't reflect my current knowledge and beliefs.

# Coding Windows Services in C++

18:31
Fri
01
Oct 2010

Services in Windows are like daemons in Linux - resident programs that work in background. I've recently learned how to code them in C++ using WinAPI. Here is a quick tutorial about this:

All the documentation you need to develop services can be found in MSDN Library. If you have it offline, go to: Win32 and COM Development / System Services / DLLs, Processes and Threads / SDK Documentation / DLLs, Processed, and Threads / Services. You can also read it online HERE. I talk only about native C and C++ code here, but services can also be written in .NET.

What are pros and cons of services, comparing to normal applications? Service can be automatically started with the system and work all the time, no matter if any user logs on and off. It can have extensive priviledges to access files on hard disk and the like, no matter what limitations do the logged-in user have. But service cannot interact directly with the user - it cannot show console or any window. So the only way for a service to do any input/output is to read some configuration files, write some log files or to communicate with some other client process ran by the user, e.g. via TCP socket connected to "localhost".

Service is written as a console application that uses special WinAPI functions to communicate with so called SCM - Service Control Manager. Example entry point routine looks like this:

// Standard console application entry point.
int main(int argc, char **argv)
{
    SERVICE_TABLE_ENTRY serviceTable[] = {
        { _T(""), &ServiceMain },
        { NULL, NULL }
    };
       
    if (StartServiceCtrlDispatcher(serviceTable))
        return 0;
    else if (GetLastError() == ERROR_FAILED_SERVICE_CONTROLLER_CONNECT)
        return -1; // Program not started as a service.
    else
        return -2; // Other error.
}

StartServiceCtrlDispatcher is the first service-related function used here. It needs an array because a process can implement multiple different services, but I show only single-service process here. The function blocks for the entire execution time of working service and fails if program was run as normal application, not as a service. While service is working, a callback function is being executed, which I called ServiceMain here. It should initialize service and then execute all the code in loop until system wants to stop the service. You can also exit the function and thus stop the service at any time if you want (e.g. if some critical error occured).

// Main function to be executed as entire service code.
void WINAPI ServiceMain(DWORD argc, LPTSTR *argv)
{
    // Must be called at start.
    g_ServiceStatusHandle = RegisterServiceCtrlHandlerEx(_T("SERVICE NAME"), &HandlerEx, NULL);
   
    // Startup code.
    ReportStatus(SERVICE_START_PENDING);
    g_StopEvent = CreateEvent(NULL, TRUE, FALSE, NULL);
    /* Here initialize service...
    Load configuration, acquire resources etc. */
    ReportStatus(SERVICE_RUNNING);

    /* Main service code
    Loop, do some work, block if nothing to do,
    wait or poll for g_StopEvent... */
    while (WaitForSingleObject(g_StopEvent, 3000) != WAIT_OBJECT_0)
    {
        // This sample service does "BEEP!" every 3 seconds.
        Beep(1000, 100);
    }

    ReportStatus(SERVICE_STOP_PENDING);
    /* Here finalize service...
    Save all unsaved data etc., but do it quickly.
    If g_SystemShutdown, you can skip freeing memory etc. */
    CloseHandle(g_StopEvent);
    ReportStatus(SERVICE_STOPPED);
}

RegisterServiceCtrlHandlerEx is a function that must be called first to register your application as a service, pass its name and a pointer to your control event handler function. Then you do some initialization, execute main service code in a loop and after it's time to stop it, do the cleanup and exit.

Service should report its state to the SCM with SetServiceStatus function. It can be called at any time and from any thread and informs the system about if your service is stopped, running, starting, stopping, paused etc. This function takes quite sophisticated SERVICE_STATUS structure, but I believe it can be simplified to three main cases which I enclosed in the following functions: ReportStatus reports basic status like SERVICE_STOPPED, SERVICE_RUNNING, SERVICE_START_PENDING or SERVICE_STOP_PENDING.

SERVICE_STATUS_HANDLE g_ServiceStatusHandle; 
HANDLE g_StopEvent;
DWORD g_CurrentState = 0;
bool g_SystemShutdown = false;

void ReportStatus(DWORD state)
{
    g_CurrentState = state;
    SERVICE_STATUS serviceStatus = {
        SERVICE_WIN32_OWN_PROCESS,
        g_CurrentState,
        state == SERVICE_START_PENDING ? 0 : SERVICE_ACCEPT_STOP | SERVICE_ACCEPT_SHUTDOWN,
        NO_ERROR,
        0,
        0,
        0,
    };
    SetServiceStatus(g_ServiceStatusHandle, &serviceStatus);
}

Third member of the SERVICE_STATUS structure - dwControlsAccepted - indicates which events will be accepted by the service after this call. I want to accept events informing about system shutdown and allow user to stop the service. I could also pass SERVICE_ACCEPT_PAUSE_CONTINUE here, which means I supported pausing and resuming the service.

ReportProgressStatus function reports service status during initialization and finalization - SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDING. I don't actually use it, but if the startup or shutdown of your service takes a lot of time, you should periodically report progress with this function. CheckPoint is simply a counter that should be incremented with each call, telling that service is making some progress. WaitHint is an estimated time it will take to finish initialization, finalization or to perform its next step. By default, system waits about 30 seconds for your service to start or stop and you should not exceed that without a good reason.

void ReportProgressStatus(DWORD state, DWORD checkPoint, DWORD waitHint)
{
    g_CurrentState = state;
    SERVICE_STATUS serviceStatus = {
        SERVICE_WIN32_OWN_PROCESS,
        g_CurrentState,
        state == SERVICE_START_PENDING ? 0 : SERVICE_ACCEPT_STOP | SERVICE_ACCEPT_SHUTDOWN,
        NO_ERROR,
        0,
        checkPoint,
        waitHint,
    };
    SetServiceStatus(g_ServiceStatusHandle, &serviceStatus);
}

Finally, there is a way for a service to shutdown and inform the system that some critical error occured. To do this, report SERVICE_STOPPED and pass error code. The code will be saved along with information about service failture to the system event log.

void ReportErrorStatus(DWORD errorCode)
{
    g_CurrentState = SERVICE_STOPPED;
    SERVICE_STATUS serviceStatus = {
        SERVICE_WIN32_OWN_PROCESS,
        g_CurrentState,
        0,
        ERROR_SERVICE_SPECIFIC_ERROR,
        errorCode,
        0,
        0,
    };
    SetServiceStatus(g_ServiceStatusHandle, &serviceStatus);
}

HandlerEx is a function to handle events sent by the system to control your service - stop it, pause, inform about the system shutdown or simply query for current status. You must always call SetServiceStatus in this function. It can be executed in different thread, so you must synchronize it with the code in ServiceMain. I do this with g_StopEvent - an event that will be set when the service should exit.

// Handler for service control events.
DWORD WINAPI HandlerEx(DWORD control, DWORD eventType, void *eventData, void *context)
{
    switch (control)
    {
    // Entrie system is shutting down.
    case SERVICE_CONTROL_SHUTDOWN:
        g_SystemShutdown = true;
        // continue...
    // Service is being stopped.
    case SERVICE_CONTROL_STOP:
        ReportStatus(SERVICE_STOP_PENDING);
        SetEvent(g_StopEvent);
        break;
    // Ignoring all other events, but we must always report service status.
    default:
        ReportStatus(g_CurrentState);
        break;
    }
    return NO_ERROR;
}

That's all the code I wanted to show. Now, because service cannot be run as normal program, you must learn how to install and uninstall it. Fortunately there is a simple command line program for this distributed with Windows - sc. To install your service, enter following command (exactly like this, with "binPath=" SPACE "PATH"):

sc create SERVICE_NAME binPath= FULL_PATH_TO_EXE_FILE

To uninstall it:

sc delete SERVICE_NAME

To control your service - start it, stop it or query its status - use commands:

sc start SERVICE_NAME
sc stop SERVICE_NAME
sc query SERVICE_NAME

Or simply run Administrative Tools / Services (another way to access it is Start / Run / "services.msc").

Two kinds of command line arguments can be passed to a service. First are argc, argv parameters taken by main function. They come from a command line fixed during installation of the service. Second are argc, argv arguments taken by ServiceMain function. They are different - argv[0] is the service name and the rest are arguments that you passed as additional parameters when calling "sc start" command.

Of course there is more to be told on this subject. Service can depend on some other services, can be automatically started with the system or only on demand, can have priviledges of a selected user or one of standard ones, like "LocalSystem" (biggest priviledges on local system, the default), "LocalService" or "NetworkService". See MSDN Library for details.

Comments | #c++ #windows #winapi Share

Comments

STAT NO AD
[Stat] [STAT NO AD] [Download] [Dropbox] [pub] [Mirror]
Copyright © 2004-2017