Classes

Class ServiceController() Foundation

Class function of the ServiceController class

Description

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
:addController()
Registers a controller for sending control requests to a service.
:getUpdatedControl()
This class method returns the controller instance of the specified service.
:queryAllServiceNames()
Query the names of all services which are currently installed on the system.
:removeByName()
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.

:getLastError()
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().

:setErrorControl()
Set new error control value and retrieve old one.
:setStartType()
Sets the starttype of the service to a new one
Methods for controlling services
:continue()
This class method continues a paused service.
:install()
Install the service with the specified name.
:pause()
This class method pauses a service.
:start()
This class method starts the service.
:stop()
This class method stops the service.
:uninstall()
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.

:controlsAccepted
The control commands which are accepted by the service.
:currentState
The status of the service.
:errorControl
The behaviour of the operating system on boot time.
:pathName
The pathname of the service.
:displayName
The name that is displayed for this service.
:serviceType
The type of service.
:startName
The account name under which the service is to be started.
:startType
The type of the service.
Log handling
:logSuccess()
Handles a successful control command.
:logError()
Handles error conditions.
Examples
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 "service.ch" 

CLASS Logger 
   EXPORTED: 
   INLINE METHOD write( cMsg ) 
      ? cMsg 
   RETURN SELF 
ENDCLASS 


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 ) 
   DO CASE 
   CASE cParam == "i" 
      ServiceController():install( cServiceName ) 

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

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

   CASE cParam == "u" 
      ServiceController():uninstall( cServiceName ) 
   ENDCASE 
RETURN 
Feedback

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.