| Last Update: | Tue Jan 05 20:27:28 -0700 2008 |
An interface for MS Windows Services.
Ruby 1.8.0 or later. This package is only supported for the Windows NT family of operating systems, e.g. 2000, XP, 2003, etc. It is NOT supported (and won't work) for any version of DOS or Windows 95/98/ME. It is also not supported on NT 4, as that platform is defunct. It should work on Windows XP Home, but is not officially supported for that platform.
require "win32/service"
include Win32
# Create a new service
Service.create('some_service', nil,
:service_type => Service::WIN32_OWN_PROCESS,
:description => 'A custom service I wrote just for fun'
:start_type => Service::AUTO_START,
:error_control => Service::ERROR_NORMAL,
:binary_path_name => 'C:\path\to\some_service.exe',
:load_order_group => 'Network',
:dependencies => ['W32Time','Schedule']
:service_start_name => 'SomeDomain\\User',
:password => 'XXXXXXX',
:display_name => 'This is some service',
)
# Configure a service that already exists
Service.configure(:display_name => "My Bar Service")
Service.start("foo")
Service.pause("foo")
Service.resume("foo")
Service.stop("foo")
Service.delete("foo")
Service.get_display_name("Schedule") # "Task Scheduler"
Service.get_service_name("ClipBook") # "ClipSrv"
Service.status('W32Time') => <struct Struct::ServiceStatus ...>
# Enumerate over all services, inspecting each struct
Service.services{ |s|
p s
puts
}
Service.new(service_name, host=nil, options={})
Creates a new service with +service_name+ on +host+, or the local host if no host is specified. The +options+ parameter is a hash that can contain any of the following parameters, and their default values: * display_name => service_name * desired_access => Service::ALL_ACCESS * service_type => Service::WIN32_OWN_PROCESS | Service::INTERACTIVE_PROCESS * start_type => Service::DEMAND_START * error_control => Service::ERROR_NORMAL * binary_path_name => nil * load_order_group => nil * dependencies => nil * service_start_name => nil * password => nil * description => nil
Service.configure(service_name, host=nil, options={})
Configures the named +service_name+ on +host+, or the local host if no host is specified. The +options+ parameter is a hash that can contain any of the following parameters: * service_type * start_type * error_control * binary_path_name * load_order_group * dependencies * service_start_name * password (used with service_start_name) * display_name * description
Service.config_info(service, host=nil)
Returns a ServiceConfigInfo struct containing the configuration information about +service+ on +host+, or the local host if no host is specified.
Service.create
Alias for Service.new
Service.delete(service, host=nil)
Deletes the specified +service+ on +host+. If no host is given, then it deletes it on the local machine.
Service.exists?(service)
Returns true if the specified service exists, false otherwise.
Service.pause(service, host=nil)
Pauses the specified +service+ on +host+, or the local machine if no host is provided.
Service.resume(service, host=nil)
Resumes the specified +service+ on +host+, or the local machine if no host is specified.
Service.services(host=nil, group=nil){ |struct| … }
Enumerates over a list of service types on host, or the local machine if no host is specified, yielding a Win32Service struct for each service. If a 'group' is specified, then only those services that belong to that group are enumerated. If an empty string is provided, then only services that do not belong to any group are enumerated. If this parameter is nil, group membership is ignored and all services are enumerated. The 'group' option is only available on Windows 2000 or later, and only if compiled with VC++ 7.0 or later, or the .NET SDK. The Win32Service struct contains the following members: * service_name * display_name * service_type * current_state * controls_accepted * win32_exit_code * service_specific_exit_code * check_point * wait_hint * binary_path_name * start_type * error_control * load_order_group * tag_id * start_name * dependencies * description * interactive? * pid (Win2k or later) * service_flags (Win2k or later) Note that the 'pid' and 'service_flags' members are only available on Windows 2000 or later, and only if built with VC++ 7.0 or later (or the .NET SDK).
Service.start(service, host=nil, *args)
Starts the specified +service+ on +host+, or the local machine if no
host is specified. Any +args+ passed here are passed as start parameters
to the service.
Service.status(service)
Returns a Win32ServiceStatus struct for the specified service (or
raises a Win32::ServiceError if not found). The Win32ServiceStatus
struct contains the following members.
* service_type
* current_state
* controls_accepted
* win32_exit_code
* service_specific_exit_code
* check_point
* wait_hint
* interactive?
Service.stop(service, host=nil)
Stops the specified +service+ on +host+, or the local machine if no
host is specified.
binary_path_name
The binary to be used for the service. The path must be the fully qualified path name. A path that contains a space must be quoted so that it is correctly interpreted. The path may also include arguments to the service entry point (typically the 'main' function).
dependencies
Any dependencies the service has in order to run. This can be a string or an array of strings.
description
A text string describing the service.
display_name
The display name to be used by user interface programs to identify the service. The string has a maximum length of 256 characters. Case sensitivity is preserved. The default is to set the display name to the same string as the service name.
error_control
The error control for the service. The default is Service::ERROR_NORMAL. See the "Error Control Contants" section for available options and their meanings.
load_order_group
The load order group, a string that names the load ordering group of which this service is a member. The default is nil.
password
Sets the passsword to the account name specified in the Service#start_name method. By default, this value is set to nil, which is appropriate if the account has no password or if the service runs in the 'LocalService', 'NetworkService', or 'LocalSystem' account. Note that passwords are ignored for driver services.
service_name
The service name for the service. This value must be set in order to create a service. The string has a maximum length of 256 characters.
service_type
The service type for the service. The default is Service::WIN32_OWN_PROCESS | Service::INTERACTIVE_PROCESS. See the "Service Type Contants" section for available options and their meanings.
start_name
Sets the name of the account under which the service should run. By default the 'LocalSystem' account is used.
start_type
The start type for the service. The default is Service::DEMAND_START. See the "Start Type Contants" section for available options and their meanings.
VERSION
The current version number of this package, returned as a string.
Service::MANAGER_ALL_ACCESS
Includes STANDARD_RIGHTS_REQUIRED, in addition to all access rights
in the table.
Service::MANAGER_CREATE_SERVICE
Required to call the CreateService function to create a service object
and add it to the database.
Service::MANAGER_CONNECT
Required to connect to the service control manager.
Service::MANAGER_ENUMERATE_SERVICE
Required to call the EnumServicesStatus function to list the services
that are in the database.
Service::MANAGER_LOCK
Required to call the LockServiceDatabase function to acquire a lock on the
database.
Service::MANAGER_BOOT_CONFIG
Required to call the NotifyBootConfigStatus() (internal) function. Not
defined with all compilers.
Service::MANAGER_QUERY_LOCK_STATUS
Required to call the QueryServiceLockStatus() (internal) function to
retrieve the lock status information for the database.
Service::FILE_SYSTEM_DRIVER
File system driver service.
Service::KERNEL_DRIVER
Driver service.
Service::WIN32_OWN_PROCESS
Service that runs in its own process.
Service::WIN32_SHARE_PROCESS
Service that shares a process with one or more other services.
Service::INTERACTIVE_PROCESS
The service can interact with the desktop. This can only be used if
either SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS is
specified as well, and the service is running in the context of the
LocalSystem account (which is the default for this module, btw).
Service::AUTO_START
A service started automatically by the service control manager during
system startup.
Service::BOOT_START
A device driver started by the system loader. This value is valid only
for driver services.
Service::DEMAND_START
A service started by the service control manager when a process calls
the StartService() function.
Service::DISABLED
A service that cannot be started. Attempts to start the service result
in an error.
Service::SYSTEM_START
A device driver started by the IoInitSystem() function. This value is
valid only for driver services.
Service::ERROR_IGNORE
The startup program logs the error but continues the startup operation.
Service::ERROR_NORMAL
The startup program logs the error and puts up a message box pop-up but
continues the startup operation.
Service::ERROR_SEVERE
The startup program logs the error. If the last-known-good configuration
is being started, the startup operation continues. Otherwise, the system
is restarted with the last-known-good configuration.
Service::ERROR_CRITICAL
The startup program logs the error, if possible. If the last-known-good
configuration is being started the startup operation fails. Otherwise,
the system is restarted with the last-known-good configuration.
See the MSDN API with regards to CreateService(), etc at http://www.msdn.com Some API ideas taken (or not) from both Python's win32serviceutil.py and Perl's Win32::Service module. I don't truly understand how to allow a tag_id in the create_service() method, so for now it's set to NULL automatically. Suggestions welcome.
There may be a failure in the test suite if the W32Time dependency is not started. If you find any bugs please log them on the bug tracker. You can find it on the project page at http://www.rubyforge.org/projects/win32utils.
Many thanks go to Patrick Hurley for providing the fix for the thread blocking issue. Thanks also go to Kevin Burge for his patch that solved service responsiveness issues.
Add Tag_ID support. Add ability to create or modify service failure actions. Use RegisterServiceCtrlHandlerEx().
(C) 2003-2008, Daniel J. Berger, All Rights Reserved
Ruby's
This package is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantability and fitness for a particular purpose.