ServiceMill Control Documentation

Overview

ServiceMill Control is an easy to use OCX control that lets you quickly and easily turn your VB application into a native Windows NT/2000/XP/2003 service. ServiceMill has 3 operating modes: Service, Simulation and Admin:

  • The control will be in Service mode when your application is started as a service by the Windows Service Manager.
  • The control will be in Simulation mode at design time. In this mode you can simulate all Service manager events (Start, Stop, Pause, etc.) 
  • The Admin mode is used when you want to control, from an external application, your service or any other service anywhere on your network.

Demo version

The demo version is a fully functional version. The only limitation is that the service will automatically stop after 30 minutes of execution.

Things you should know about Windows NT Services

<Security context>
Windows Services run in their own security context, not the context of the currently logged on user.
A Service can be configured to be started under a system account security context or under a Windows user security context.
If your service needs to access network resources (files, printers, etc.) you will need to configure your service to start under a user account.
Also, if your service starts an application, the application will run in the same security context as your service. Application such as Microsoft Office will require your service to be started under a user account, not a system account.

<Desktop>
Services run in their own virtual desktop. This means that any user interface displayed by a service will not be visible by the logged on user, therefore a service cannot display any blocking user interface, such as a message box when an error occurs. It is however possible for a service to access the active user desktop (the active user desktop is the desktop that is displayed on the monitor when a user is logged on the machine). To access the desktop you will need to start the service under a system account with the "Interact with Desktop" option checked.

<ODBC>
To access ODBC databases, you will need to create a "System DSN" and not a "User DSN".

For an indepth technical overview of Windows Services we recommend that you read article Inside Win32 Services written by the NT guru Mark Russinovich from SysInternals

Converting your application into a Service
  1. - Insert the ServiceMill control in your application main form
  2. - Put all your initialization code in the Start() event.
  3. - Put all your uninitialization code in the Stop()  event.
  4. - Insert a Timer control in the application main form and implement in the Timer() event the code that will do the actual service work. Note: You may use any other activation method to perform the service work, you don't need to use a timer.
  5. - Done

Now you need to Install your service:

You can either put the installation code in your setup program or you can implement a command line handler in your service program (e.g. yoursvc.exe /install).

  1. - Set the ServiceName, DisplayName and StartupType properties
  2. - Call the Install() method (Note: you must compile your program into an exe before executing the Install() method).
  3. - Done
Debugging

To debug your service, run the service from your development environment (e.g. Visual Basic) and right click over the control. You will see a list of all possible commands that the Windows Service Manager can generate (Start, Stop, Pause, etc.). When your program is running as a service, you can use the LogEvent method to report messages to the Event Log. Additionally, you can install the Service+ utility available on the Active+ Software Web site. Service+ will provide you with a much better control over services than what comes with the operating systemthe original Windows NT Control Panel Services applet. (e.g. You can monitor Pending states, kill unresponding services, etc.).

Communicating with your Service

There are many different ways to communicate between a service and an application (TCP/IP Sockets, DCOM, RPCs, File sharing, etc.)
ServiceMill Control provides a function named SendData that let you send any kind of data that can be encapsulated into a Variant (an Integer, a String, an Array of Variant, an Array of String, etc.) 

Shipping ServiceMill Control with your application

You need to include the file svcit.ocx with your software package. Svcit.ocx is a self registration DLL, you may use the DLL Registration Utility (regsvr32.exe) or other registration API such as DllRegisterServer().

Properties
Access, Mode (0,1,2) Comments
Mode as Long RW Set the Control mode
0 - Service (Automatically set when the process is started as a service)
1 - Service Simulation (Debug at design time)
2 - Administration
PauseContinue as Boolean RW,0,1 Set this property to true to enable the service manager to Pause/Continue the service.
WaitHint as Long RW,0,1 Maximum delay for a pending state in milliseconds, default is 60 seconds. The service is in a pending state during the execution of the Start(), Stop(), Pause() and Continue() events. If the service takes more time than what is set in WaitHint during the event calls, the service manager will consider the service failed to achieve it's requested state (Running, Paused or Stopped). The WaitHint property can also be set within a pending event to allow more time than what was set by default 
Priority as Long RW,0,1 Set the service priority (0 Normal, 1 Idle, 2 High). If you want your service to run only when Windows NT as nothing much to do, set the priority to 1 (Idle).
ServiceName as String RO 0,1
RW 2		 The service name. Avoid using long names and spaces.
DisplayName as String RO 0,1
RW 2		 The service display name
StartType as Long RO 0,1
RW 2		 0 – Automatic
1 – Manual
2 – Disabled
Interact as Boolean RO 0,1
RW 2		 The Service can interact with the desktop when this property is set to True. Only system account services can interact with the desktop.
Dependencies as String RO 0,1
RW 2		 List of dependent services separated by ";".
It is recommended to make your service dependent of the Workstation service, this will assure that most NT components will be started before your service starts.
Account as String RO 0,1
RW 2		 User account used to start the service, if not set the service will start as a system account. If you need to access network resources you cannot start the service as a system account. The account name must include the domain name (e.g. domain\user), if the account is local to the machine use .\user
Password as String WO 2 User account password
MachineName as String RO 0,1
RW 2		 Target computer name
ServiceExe as String RO 0,1
RW 2		 String that contains the fully qualified path to the service executable file (the default is the current process executable)
Description RO 0,1
RW 2		 The service description. This property will only work when running on Windows 2000 or later  
StopServiceOnClose RW 0,1 If set to True, the service will be stopped if the application primary window is closed. 
Using VB: To prevent a user from closing the application, on  the Form_Unload event, set Cancel to True and set this property to False.
Events
Mode Comments
Start(Params as String) 0,1 This event is fired when the service is starting. Initialization should be performed here. You can abort the service startup by Calling the Abort() method followed by the End statement. The initialization cannot take more time than what is set in the WaitHint property. The service will be in a start pending state until you exit the Start event
Stop() 0,1 This event is fired by the service manager when the service is stopped or when the Stop() method is called. The uninitialization of your service should be performed here. You do not need to exit your application, the control will close your application for you. The service will be in a stop pending state until you exit the Stop event
Pause() 0,1 This event is fired by the service manager when the service is paused or when the Pause() method is called. The PauseContinue property must be set to True to enable access to the service Pause event. The service will be in a pause pending state until you exit the Pause event
Continue() 0,1 This event is fired by the service manager when the service was previously in paused state. The service will be in a continue pending state until you exit the Continue event
Control(Code as Long) 0,1 This event can be fired by another application to perform a custom service control. The service defines the action associated with the control code. The code must be between 128 and 255. This call will be handled asynchronously by the service, therefore, the call could return before the service task is fully completed.
Shutdown() 0 This event is fired when Windows is shutting down. The service should terminate as fast as possible.
Logoff() 0 This event is fired when the currently logged on user is logging off. This event will only be generated if the service has the "Interact with Desktop" option enabled.
ReceiveData(Data As Variant, Result As Variant) 0,1 This event is fired when a client calls the SendData method.
See the SendData function for details.
     
Methods
Mode Comments
Abort(Error as Long, SpecificError as Long) 0 The Abort method can be called during the service startup (Start Event) to abort startup. The service can report to the service manager a standard Windows NT error or a specific error code. To report a specific error code, set the Error parameter to 0. Note that the Stop event will not be called when the Abort method is called. You must not call the Stop() method after calling the Abort() method. Call the End statement instead.
Start(sParams as String) 1,2 The application can call this method to simulate a service Start() event. This method cannot be called when the application is running as a service.
Stop() 0,1,2 The application can call this method at any time to stop the service. The Stop event will be called.
Pause() 0,1,2 The application can call this method at any time to pause the service. The Pause event will be called.
Continue() 0,1,2 The application can call this method at any time to reset the service to a running state. The Continue event will be called.
IsRunning() 0,1,2 Returns True if the service is in a running state.
IsPaused 0,1,2 Returns True if the service is in a paused state.
IsService() 0,1,2 Returns True if the application is running as a true service or not. A true service is a service that was started by the Windows NT Service Manager.
IsAdmin() 0,1,2 Returns True if the current process is running with administrative rights.
Note: Administrative rights are required to control a service (Install, Remove, Start, Stop, etc.)
Install(Start as Boolean) 2 The Install method will install your service in the service control manager database. You must compile your program into an executable or set the ServiceExe for this method to work. The property ServiceName, DisplayName, StartType must be set. Optionally the Dependencies, Account, Password and Interact properties can be set.
Set the Start parameter to True if you want your service to start immediately.
Required security privileges will be granted to the user account
Remove() 2 The Remove method will remove the service from the service control manager database. The ServiceName property must be set. If the service is running, it will be stopped.
IsInstalled() 2 Returns True if the service is installed. The property ServiceName must be set.
LogEvent(Message as String, Type as Long) 0,1,2 You can call this method to Log an event in the Application EventLog (Windows NT Only).
Events type:
1 - Error
2 - Warning
4 - Information
Variant SendData(Data as Variant) 2 This method may be used to send data from a client to a ServiceMill Control service. The service may be located on a different  machine. The service will receive this data through the ReceiveData event. The Data parameter can contain any kind of variants excluding objects and multi dimensional arrays. The ReceiveData event can also return data to the client.