The header also defines a string type called ServiceString that is either std::string or std::wstring , depending on the character set used to build the native project. This is the type used for string in the C++ service components.

Service Handle

Functions such as OpenSCManager and OpenService (but also CreateService ) return a SC_HANDLE that is a pointer value. However, the handle must be closed after the code that requires the handle finishes execution. To simplify the correct closing of service handles in all cases, the handle will be wrapped in a class that calls CloseServiceHandle when the object is destroyed, in a RAII fashion. Such an implementation is available in the ServiceHandle.h header.

ServiceController Class

The ServiceController class represents a Windows service and allows you to query and change the service status, query and change configuration data and others. This is a minimal implementation and can be extended with additional functionality as needed. The implementation is available in the header ServiceController.h .

The constructor of the class takes the service name and optionally desired access. If the access is specified, the value is SERVICE_ALL_ACCESS that means access rights for all service operations. The following calls are performed in the constructor:

You can check what control codes the service accepts and processes in its handler function by using the CanAcceptControl() method. It takes a value defined by the ServiceControls enumeration and returns a bool indicating whether the control code is accepted and processed or not. Several additional methods are defined using this method.

Checking Status

Function QueryServiceStatusEx is also used to check the status of the service (such as stopped, running, starting, etc.). This function returns information in a SERVICE_STATUS_PROCESS structure. The dwCurrentState member represents the current status as defined by the ServiceStatus enumeration.

Changing Status

Services can be started and stopped and some services can be paused and continued. The ServiceController class provides methods for all these four operations.

To start the service, we must call StartService . This function takes the service handle and optionally arguments to be passed to the ServiceMain function of the service. In this implementation, no parameters are passed.

The Stop() , Pause() and Continue() methods are implementing using the ControlService function. This function takes the service handle, a control code that represents a notification to be sent to the service and an object of type SERVICE_STATUS that receives the latest service status information.

The implementation of the Stop() method is a little bit different though than of Pause() and Continue() because the service might have dependent services and those also need to be stopped when the service is stopped. Stopping the dependent services is implemented in the StopDependentServices() private function. This function does the following:

Should any of the dependent services fail to properly stop, the rest of the routine will not execute and the main service will not be stopped. Notice that when waiting for the service, we have a timeout set for 30 seconds by default. If the service does not stop within this interval, the routine fails.

Waiting for the Status to Change

When you start, stop, pause or continue a service, the change of status might not happen instantly. For instance, starting a service could take several seconds. The Start() , Stop() , Pause() and Continue() methods return immediately, indicating only that the change request has been completed successfully, not that the status was indeed changed. (Notice that Stop() returns immediately after requesting the stopping of the service, but does wait for all the dependent services to stop first.)

To check the status has changed, you need to periodically query the service status until it changes to the desired state. The ServiceController class provides a method that does that called WaitForStatus() . The method takes as parameters the desired status and a timeout (set by default to 30 seconds). It first queries the service status and if the service is not in the desired state, then it puts the current thread to sleep for a while and then repeats the operation. The loop ends either when the state has been changed to the desired state or when the timeout elapses. Notice that the sleep interval is 1/10 ^th of the service's wait hint, but not smaller than 1 second and not larger than 10 seconds.

Deleting the Service

To delete a service, we must call the DeleteService function. This function however only marks the service for deletion from the service control manager database. The service is deleted only when all open handles to the service have been closed and the service is not running. If the service is running at the time of the call, the database entry is removed when the system is restarted.

ServiceConfig Class

The ServiceConfig class represents the configuration parameters of a service. It enables you to read and update some of these configuration parameters and it can be extended if needed to include additional parameters. It is available in the header ServiceConfig.h .

The parameters that are automatically read are: the service type, the startup type, the error control for startup failure, the path name, the load ordering group name, the tag ID, the dependent services, the start name, the display name and the description.

The parameters that can be modified in the current implementation are the start type, the error control and the description. For other parameters, the class must be extended with appropriate methods.

An instance of the class can be created using the static method ServiceConfig::Create that takes a handle to an existing service. After creating an object, this function called its Refresh() method to read the configuration parameters.

The Refresh() method does the following:

To modify the configuration parameters, several methods are available:

To retrieve the configuration parameters of a service, you should use the GetServiceConfig() method of the ServiceController class. It returns an instance of the ServiceConfig class.

Notice : if you explicitly call the ServiceConfig::Create() method, you must make sure the SC_HANDLE is properly closed when you no longer need to interact with the service.

ServiceEnumerator Class

The ServiceEnumerator class is basically a small utility class for enumerating existing services. It contains a single static method called EnumerateServices that takes several parameters for the service type and state, the machine and service control database name and the load-order group name. With the default values for these parameters, the function enumerates all services, regardless of their type and state, on the local machine.

To enumerate the services, this function:

Conclusions

In this article, we have built several C++ components for managing Windows services to simplify the use of the Windows service APIs in a C++ application. Along the way, we have also seen what are the Windows service APIs and how they should be used. For a complete reference on the API, see Service Functions in MSDN.

History

Those handle moves are in the move constructor and move assignment operator. Leaving the original instance with no handle to the service is these members' purpose. They are intended to take ownership.
Sign In · View Thread

On further examination, it appears that the move constructor isn't quite right. It should be
ServiceHandle(ServiceHandle&& other) noexcept : _handle( std::move (other._handle)) other._handle = nullptr ; Web04 2.8:2023-03-27:1