Service-It Control
Overview
Service-It Control is an easy to use OCX control that
lets you quickly and easily turn your application into a native Windows NT service.
Service-It 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 NT Service Manager.
The Simulation mode can be used to run your program unmodified on Windows 95/98 or when
you debug your service.
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 NT 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 NT 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".
Steps needed to convert your application to run as a service with the Service-It Control:
- Insert the Service-It control in your application
main form.
- Put all your initialization code in the Start() event.
- Put all your uninitialization code in the Stop() event.
- 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.
- 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)
- Set the ServiceName, DisplayName and StartupType
properties
- Call the Install() method (Note: you must compile your program into an exe before
executing the Install() method).
- 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 NT 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 NT services than the original Windows NT Control Panel Services applet. (e.g. You can monitor Pending states, kill unresponding services, etc.).
Communicating with your service from an another application
There are many different way to communicate between a service and an
application.
A simple way to communicate is to use the private service
control code. You can send any value from 128 to 255 to your service. For example you
could use the code 128 to tell your service to reload some new settings from the registry.
Private control code can also be sent from a remote machine.
Other technologies such as DCOM, TCP/IP Sockets, File Sharing, Volatile Registry Key, RPC,
etc. can be used
Shipping Service-It 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).
Note: On the Windows 95 platform, you also need to redistribute the mfc42.dll and
msvcrt.dll files.
Properties
| Access, Mode (1,2,3) | Comments | |
| Mode as Long | RW | Set the Control mode 0 - Service (Automatically set when the process is started as a service) 1 - Service Simulation 2 - Administration (Windows NT Only) |
| PauseContinue as Boolean | RW,1,2 | Set this property to true to enable the service manager to Pause/Continue the service. |
| WaitHint as Long | RW,1,2 | Maximum delay for a pending state, default is 60 seconds. The service is in a pending state during the execution of the Start(), Stop(), Pause() and Continue() event. If the service takes more time than what is set in WaitHint during these calls, the service manager will consider the service failed to achieve it's requested state (Running, Paused or Stopped). |
| Priority as Long | RW,1,2 | 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 1 RW 2,3 |
The service name. Avoid using long names and spaces. |
| DisplayName as String | RW 2,3 | The service display name |
| StartType as Long | RW 2,3 | 0 – Automatic 1 – Manual 2 – Disabled |
| Interact as Boolean | RW 2,3 | 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 | RW 2,3 | 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 | RW 2,3 | 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. |
| Password as String | WO 3 | User account password |
| MachineName as String | RW 3 | Target computer name |
| ServiceExe as String | RW 3 | String that contains the fully qualified path to the service executable file (the default is the current process executable) |
Events
| Mode | Comments | |
| Start(Params as String) | 1,2 | The Start event is called 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() | 1,2 | The Stop event is called when the service is stopped by the service manager 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() | 1,2 | The Pause event is called when the service is paused by the service manager 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() | 1,2 | The Continue Event is called 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) | 1,2 | The control event can be called 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. |
| Shutdown() | 1 | The shutdown method is called by the service manager when Windows NT is shutting down. The service should terminate as fast as possible. |
Methods
| Mode | Comments | |
| Abort(Error as Long, SpecificError as Long) | 1 | 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) | 2,3 | 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() | 1,2,3 | The application can call this method at any time to stop the service. The Stop event will be called. |
| Pause() | 1,2,3 | The application can call this method at any time to pause the service. The Pause event will be called. |
| Continue() | 1,2,3 | The application can call this method at any time to reset the service to a running state. The Continue event will be called. |
| IsRunning() | 1,2,3 | Determine if the service is in a running state. |
| IsPaused | 1,2,3 | Determine if the service is in a paused state. |
| IsService() | 1,2 | Determine 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() | 1,2,3 | Determine 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) | 1,2,3 | 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() | 1,2,3 | 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() | 1,2,3 | Determine if the service is installed. The property ServiceName must be set. |
| LogEvent(Message as String, Type as Long) | 1,2,3 | You can call this method to Log an event
in the Application EventLog (Windows NT Only). Events type: 1 - Error 2 - Warning 4 - Information |
Technical support is provided online at the Active+ Software web site
Copyright © 1998-1999 Active+ Software. All rights reserved.