Class ServiceController() Foundation

Class function of the ServiceController class


This class implements the mechanism to control a service application. Basically it provides the interface to Start, Stop, Pause and Continue a service on service capable Windows platforms.

In addition, this class can be used to query the current status of a service. The method :queryAllServiceNames() returns an array of all installed services. By calling :getUpdatedControl(), an instance of this class is returned whose member variables :serviceType, :currentState, :controlsAccepted, :startType, :errorControl, :pathName, :startName and displayName contain status information of the service.

instances of this class serve informational purposes only. Therefore no :init() method is implemented. All services to be controlled are to be registered with the class method :addController().

For technical basics please refer to the section Controling services.

Managing service controller
Registers a controller for sending control requests to a service.
This class method returns the controller instance of the specified service.
Query the names of all services which are currently installed on the system.
Removes a service controller when it is no longer required.
Error information

Whenever an error occurs during a call to one of the methods :install(), :uninstall(), :start(), :stop(), :pause() and :continue() , the reason of the error can be retrieved with the method :getLastError(). Additionally the method :logError() is called.

Retrieves the number of the last error.
Change service behavior

This group lists class methods that change the behavior of a service. All methods of this group must be called after a controller for the service is registered with the class method :addController() but before the service is installed with :install().

Set new error control value and retrieve old one.
Sets the starttype of the service to a new one
Methods for controlling services
This class method continues a paused service.
Install the service with the specified name.
This class method pauses a service.
This class method starts the service.
This class method stops the service.
Uninstall a service on the system.
Status Information

After the control object is retrieved with the class method :getUpdatedControl()services status information is stored in instance variables of the returned object.

The control commands which are accepted by the service.
The status of the service.
The behaviour of the operating system on boot time.
The pathname of the service.
The name that is displayed for this service.
The type of service.
The account name under which the service is to be started.
The type of the service.
Log handling
Handles a successful control command.
Handles error conditions.
Implementation of a service controller
// This example implements the controller for the service MyService. 
// (see the example for the ServiceApp() class) 
// It is assumed that the executable of the service has the same 
// location as this controller. 
// With this controller it is possible to install, start, stop and to 
// uninstall the service. 

#include "" 

CLASS Logger 
   INLINE METHOD write( cMsg ) 
      ? cMsg 

PROCEDURE Main( cParam ) 
   LOCAL cLocation, oLog, oCtrl, cServiceName 

   cServiceName := "MyService" 
   cLocation    := CurDrive() + ":\" + CurDir() + "\" 
   oLog         := Logger():new() 
   oCtrl        := ServiceController() 

   oCtrl:addController( cServiceName ,                       ; 
                        "Alaska Software Service Sample"   , ; 
                        cLocation + cServiceName + ".exe"  , ; 
                        ".\Frodo", "Hobbit",               , ; 
                        oLog ) 
   CASE cParam == "i" 
      ServiceController():install( cServiceName ) 

   CASE cParam == "s" 
      ServiceController():start( cServiceName ) 

   CASE cParam == "x" 
      ServiceController():stop( cServiceName ) 

   CASE cParam == "u" 
      ServiceController():uninstall( cServiceName ) 

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.