Windows API Reference: Service Management

This section provides comprehensive documentation on the Windows API functions and structures used for managing services. Services are long-running executable applications that run in the background, typically without a direct user interface. They are essential for system operations, network services, and various background tasks.

Overview

The Windows Service Control Manager (SCM) is responsible for managing services. It allows you to install, start, stop, query, and delete services. The SCM also provides mechanisms for inter-service communication and dependency management.

Key components and concepts include:

Service Control Manager (SCM): The core component that manages services.
Service Control Handler: Functions that a service implements to receive control requests from the SCM.
Service Status: Information about the current state of a service (running, stopped, pending, etc.).
Service Dependencies: Services that must be running before another service can start.
Service Accounts: The security context under which a service runs.

Key Functions

Below are some of the most commonly used API functions for service management:

Starting and Stopping Services

BOOL StartService(SC_HANDLE hService, DWORD dwNumServicesArgs, LPCTSTR* lpServiceArgVectors);

Starts a specified service and its dependencies. Returns TRUE on success, FALSE otherwise.

BOOL ControlService(SC_HANDLE hService, DWORD dwControl, LPSERVICE_STATUS lpServiceStatus);

Sends a control code to a service. Common control codes include SERVICE_CONTROL_STOP, SERVICE_CONTROL_PAUSE, and SERVICE_CONTROL_CONTINUE. Returns TRUE on success, FALSE otherwise.

Querying Service Status

BOOL QueryServiceStatus(SC_HANDLE hService, LPSERVICE_STATUS lpServiceStatus);

Retrieves the current status of a specified service. The LPSERVICE_STATUS structure contains information like the service state, controls accepted, and exit code.

Service Installation and Deletion

SC_HANDLE CreateService(SC_HANDLE hSCManager, LPCTSTR lpServiceName, LPCTSTR lpDisplayName, DWORD dwDesiredAccess, DWORD dwServiceType, DWORD dwStartType, DWORD dwErrorControl, LPCTSTR lpBinaryPathName, LPCTSTR lpLoadOrderGroup, LPDWORD lpdwTagId, LPCTSTR lpDependencies, LPCTSTR lpServiceStartName, LPCTSTR lpPassword);

Creates a new service entry in the service control manager database. Requires administrative privileges.

BOOL DeleteService(SC_HANDLE hService);

Deletes an entry for a service from the service control manager database. The service must be stopped. Requires administrative privileges.

Accessing the Service Control Manager

SC_HANDLE OpenSCManager(LPCTSTR lpMachineName, LPCTSTR lpDatabaseName, DWORD dwDesiredAccess);

Opens a connection to the service control manager on the specified computer. Requires appropriate access rights.

BOOL CloseServiceHandle(SC_HANDLE hSCObject);

Closes a handle to a service or the service control manager. It's crucial to release these handles to prevent resource leaks.

Service Status Structure

`SERVICE_STATUS`

Member	Description
`DWORD dwServiceType`	The type of service (e.g., `SERVICE_KERNEL_DRIVER`, `SERVICE_FILE_SYSTEM_DRIVER`, `SERVICE_WIN32_OWN_PROCESS`, `SERVICE_WIN32_SHARE_PROCESS`).
`DWORD dwCurrentState`	The current state of the service. Can be `SERVICE_STOPPED`, `SERVICE_START_PENDING`, `SERVICE_STOP_PENDING`, `SERVICE_RUNNING`, `SERVICE_CONTINUE_PENDING`, `SERVICE_PAUSE_PENDING`, `SERVICE_PAUSED`.
`DWORD dwControlsAccepted`	Indicates the control codes the service accepts.
`DWORD dwWin32ExitCode`	The exit code that the service uses when it stops.
`DWORD dwServiceSpecificExitCode`	A service-specific exit code.
`DWORD dwCheckPoint`	Used to report progress of pending operations.
`DWORD dwWaitHint`	Estimated time in milliseconds the service needs to complete the current operation.

Examples

A simple example of how to start a service:


#include <windows.h>
#include <iostream>

int main() {
    SC_HANDLE hSCManager = OpenSCManager(NULL, NULL, SC_MANAGER_CREATE_SERVICE);
    if (hSCManager == NULL) {
        std::cerr << "Failed to open Service Control Manager: " << GetLastError() << std::endl;
        return 1;
    }

    // Assume "MyService" is the service name
    SC_HANDLE hService = OpenService(hSCManager, L"MyService", SERVICE_START);
    if (hService == NULL) {
        std::cerr << "Failed to open service: " << GetLastError() << std::endl;
        CloseServiceHandle(hSCManager);
        return 1;
    }

    if (!StartService(hService, 0, NULL)) {
        if (GetLastError() != ERROR_SERVICE_ALREADY_RUNNING) {
            std::cerr << "Failed to start service: " << GetLastError() << std::endl;
            CloseServiceHandle(hService);
            CloseServiceHandle(hSCManager);
            return 1;
        } else {
            std::wcout << L"Service is already running." << std::endl;
        }
    } else {
        std::wcout << L"Service started successfully." << std::endl;
    }

    CloseServiceHandle(hService);
    CloseServiceHandle(hSCManager);
    return 0;
}