win32-service 0.7.0-x86-mswin32-60 → 0.7.1-x86-mswin32-60

data/doc/service.txt

@@ -1,368 +1,365 @@
-= Description
-   An interface for MS Windows Services.
-    
-= Prerequisites
-   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.
-    
-= Synopsis
-   require "win32/service"
-   include Win32
-    
-   # Create a new service
-   Service.create(
-      :service_name       => 'some_service', 
-      :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
-   }
-    
-= Class Methods
-Service.new(options={})
-   Creates a new service. The +options+ parameter is a hash that can
-   contain any of the following parameters, and their default values:
-   
-   * service_name       => nil (mandatory)
-   * host               => nil
-   * 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(options={})   
-   Configures an existing service. The +options+ parameter is a hash that can
-   contain any of the following parameters:
-   
-   * service_name (mandatory)
-   * host
-   * 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.	
-    
-= Create and configure options
-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.
-    
-= Constants
-
-=== Standard Constants
-VERSION
-    The current version number of this package, returned as a string.
-    
-=== Desired Access Constants
-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 Type Constants
-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).
-    
-=== Start Type Constants
-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.
-    
-=== Error Control Constants
-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.
-    
-= Notes
-   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.
-    
-= Known Bugs
-   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.
-   
-= Acknowledgements
-   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.
-    
-= Future Plans
-   Add Tag_ID support.
-   Add ability to create or modify service failure actions.
-   Use RegisterServiceCtrlHandlerEx().
-    
-= Copyright
-   (C) 2003-2009, Daniel J. Berger, All Rights Reserved
-    
-= License
-   Artistic 2.0
-    
-= Warranty
-   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.
-    
-== Author(s)
-* Daniel J. Berger   
-* Park Heesob
+= Description
+   An interface for MS Windows Services.
+    
+= Prerequisites
+   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.
+    
+= Synopsis
+   require "win32/service"
+   include Win32
+    
+   # Create a new service
+   Service.create(
+      :service_name       => 'some_service', 
+      :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
+   }
+    
+= Class Methods
+Service.new(options={})
+   Creates a new service. The +options+ parameter is a hash that can
+   contain any of the following parameters, and their default values:
+   
+   * service_name       => nil (mandatory)
+   * host               => nil
+   * 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(options={})   
+   Configures an existing service. The +options+ parameter is a hash that can
+   contain any of the following parameters:
+   
+   * service_name (mandatory)
+   * host
+   * 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.	
+    
+= Create and configure options
+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.
+    
+= Constants
+
+=== Standard Constants
+VERSION
+    The current version number of this package, returned as a string.
+    
+=== Desired Access Constants
+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 Type Constants
+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).
+    
+=== Start Type Constants
+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.
+    
+=== Error Control Constants
+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.
+    
+= Notes
+   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.
+    
+= Known Bugs
+   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.
+   
+= Acknowledgements
+   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.
+    
+= Future Plans
+   Add Tag_ID support.
+   Add ability to create or modify service failure actions.
+   Use RegisterServiceCtrlHandlerEx().
+    
+= Copyright
+   (C) 2003-2010, Daniel J. Berger, All Rights Reserved
+    
+= Warranty
+   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.
+    
+== Author(s)
+* Daniel J. Berger   
+* Park Heesob