Programming Guide:xppguide

Controlling services Foundation

This chapter discusses the basic functionality of a service control application. Please refer to the reference documentation of the ServiceController() class for details, further reading and an example.

Since services normally start during system startup, they are not controlled like ordinary GUI applications that provide a user interface. A user starts and executes such applications by double clicking their icon. Service applications, in contrast, are controlled by the Service Control Manager (SCM). It is the responsibility of the SCM to forward any control request to a specific service.

Install and uninstall

A service application must be installed so that the operating system knows of its existence and recognizes the service in future. The user who is installing (and uninstalling services of course) must be logged in as System Administrator.

To install a service means in technical terms that the service application is simply registered in the Windows Registry. In Xbase++, this is a task of the ServiceController() class which provides an interface for (un)installing services. When the operating system boots, the SCM simply iterates through the respective registry entries and tries to start all service applications that are scheduled to run immediately after system startup.

It must be emphasized that the installation of a service is complete when data required to start a service is entered in the Registry. However, there is no data validation at this stage. Whether or not data is correct is determined only when a service is started, not when it is installed. A common error at installation is, for example, a lack of security rights of the user account under which a service is scheduled to be started.

When installing a service, its behaviour may be specified. It is possible, for example, to force a system reboot with the last known working configuration when a single service fails to start.

When a service is no longer needed, it can be uninstalled. This removes it from the Windows Registry and the application is no longer executed during system startup.

Security rights

By default, services exist in a special account named LOCAL ACCOUNTwhen being started. This must be taken into account when deploying service applications. Services must not use any resources unavailable in this environment, like network resources, for example. As a rule of thumb, services programmed with Xbase++ should be deployed on a local drive and the entire Xbase++ runtime environment should be accessible for the service application. This requires the environment variables PATHand LIB to point to the location of the Xbase++ runtime libraries.

It is possible, however, to run a service under a different account. In this case it must be installed accordingly and, again, security issues must be taken care of. An account under which a service is executed must gain the rights Log on as service, otherwise the start of the service fails.

Control requests

A service is running immediately after system startup since the SCM sends a Start Control Request to the service. If the service is successfully started, it changes its state from Stopped to Running. A service may then be stopped by instructing the SCM to pass a Stop Control Request to the service. Sending Start and Stop requests via SCM to a service is usually done during maintenance and, of course, development of services.

The state Running of a service indicates that it is successfully started by the SCM. The service keeps this state until it receives a new Control Request from the SCM that changes this state. It is important to know that the operating system does not grant any mechanism to detect whether or not a particular service is still alive. If, for example, a runtime error occurs after a service is started, the service keeps the state Running even if it may have terminated. Thus, a service's state reflects the last control message received by a service and does not necessarily indicate its current state in traditional way.

This fact must be taken into account when developing and analyzing service applications. An unpredictable error resulting in a runtime error cannot be detected as in ordinary applications. The state of a service is only changed by passing Control Requests via the SCM.

Refer to the documentation of ServiceController() for details.


If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.