win32-service 0.7.1 → 0.7.2

Sign up to get free protection for your applications and to get access to all the features.
data/CHANGES CHANGED
@@ -1,3 +1,10 @@
1
+ == 0.7.2 - 7-Sep-2011
2
+ * Now works with mingw compiler by skipping __try and __finally if using
3
+ mingw, or using them with mingw if the seh.h header is found.
4
+ * The binary gem now contains binaries for both Ruby 1.8.7 and 1.9.2 using
5
+ a simple wrapper.
6
+ * Updated some Rake tasks.
7
+
1
8
  == 0.7.1 - 9-Feb-2010
2
9
  * Compatibility fixes for 1.9.x.
3
10
  * Fixed a bug where the controls_accepted struct member was always nil. This
data/README CHANGED
@@ -2,7 +2,8 @@
2
2
  The win32-service library allows you to control or create MS Windows services.
3
3
 
4
4
  == Installation
5
- gem install win32-service
5
+ gem install win32-service # Build from source
6
+ gem install win32-service --platform x86-mingw32 # Install binary
6
7
 
7
8
  == Synopsis
8
9
  require 'win32/service'
@@ -24,7 +25,7 @@
24
25
  === Troubleshooting:
25
26
  This can be caused by one of two things. Either you attempted to delete a
26
27
  running service without stopping it first, or you have the Services
27
- administrative tool (GUI) open. In the form case, the solution is to first
28
+ Administrative Tool (GUI) open. In the former case, the solution is to first
28
29
  stop the service if it's running. In the latter, close the Services GUI
29
30
  admin tool before deleting.
30
31
 
@@ -47,10 +48,6 @@
47
48
 
48
49
  * You've got a syntax error in your code somewhere.
49
50
 
50
- == Possible test failures
51
- The 'test_service_start_stop' test in the test_win32_service.rb file may
52
- fail. This will happen if your W32Time service isn't running.
53
-
54
51
  == See Also
55
52
  ruby-wmi
56
53
 
@@ -59,7 +56,7 @@
59
56
  Add service_session_change hook
60
57
 
61
58
  == Copyright
62
- (C) 2003-2010, Daniel J. Berger, All Rights Reserved
59
+ (C) 2003-2011, Daniel J. Berger, All Rights Reserved
63
60
 
64
61
  == License
65
62
  Artistic 2.0
data/Rakefile CHANGED
@@ -4,46 +4,33 @@ require 'rake/testtask'
4
4
  require 'rbconfig'
5
5
  include Config
6
6
 
7
- desc "Cleans up the C related files created during the build"
8
- task :clean do
9
- Dir.chdir('ext') do
10
- if File.exists?('daemon.o') || File.exists?('daemon.so')
11
- sh 'nmake distclean'
12
- end
13
- File.delete('win32/daemon.so') if File.exists?('win32/daemon.so')
14
- end
15
- Dir['*.gem'].each{ |f| File.delete(f) }
16
- File.delete('lib/win32/daemon.so') if File.exists?('lib/win32/daemon.so')
17
- end
18
-
19
- desc "Builds, but does not install, the win32-service library"
7
+ CLEAN.include(
8
+ '**/*.gem', # Gem files
9
+ '**/*.rbc', # Rubinius
10
+ '**/*.o', # C object file
11
+ '**/*.log', # Ruby extension build log
12
+ '**/Makefile', # C Makefile
13
+ "**/*.so", # C shared object
14
+ "**/*.lib", # C build file
15
+ "**/*.def", # C build file
16
+ "**/*.pdb", # C build file
17
+ "**/*.exp", # C build file
18
+ "**/*.obj", # C build file
19
+ "**/*.log", # C build file
20
+ "lib/win32/ruby18", "lib/win32/ruby19", "lib/win32/daemon.rb"
21
+ )
22
+
23
+ desc "Build the win32-service library"
20
24
  task :build => [:clean] do
25
+ make = CONFIG['host_os'] =~ /mingw|cygwin/i ? "make" : "nmake"
26
+
21
27
  Dir.chdir('ext') do
22
28
  ruby 'extconf.rb'
23
- sh 'nmake'
29
+ sh "#{make}"
24
30
  FileUtils.cp('daemon.so', 'win32/daemon.so')
25
31
  end
26
32
  end
27
33
 
28
- desc "Install the win32-service library (non-gem)"
29
- task :install => [:build] do
30
- Dir.chdir('ext') do
31
- sh 'nmake install'
32
- end
33
- install_dir = File.join(CONFIG['sitelibdir'], 'win32')
34
- Dir.mkdir(install_dir) unless File.exists?(install_dir)
35
- FileUtils.cp('lib/win32/service.rb', install_dir, :verbose => true)
36
- end
37
-
38
- desc 'Uninstall the win32-service library (non-gem)'
39
- task :uninstall do
40
- service = File.join(CONFIG['sitelibdir'], 'win32', 'service.rb')
41
- FileUtils.rm(service, :verbose => true) if File.exists?(service)
42
-
43
- daemon = File.join(CONFIG['sitearchdir'], 'win32', 'daemon.so')
44
- FileUtils.rm(daemon, :verbose => true) if File.exists?(daemon)
45
- end
46
-
47
34
  namespace 'gem' do
48
35
  desc 'Build the gem'
49
36
  task :create => [:clean] do
@@ -70,6 +57,57 @@ namespace 'gem' do
70
57
 
71
58
  Gem::Builder.new(spec).build
72
59
  end
60
+
61
+ # This is for me, not for you.
62
+ desc 'Create a gem with binaries for 1.8 and 1.9'
63
+ task :binaries => [:clean] do
64
+ make = CONFIG['host_os'] =~ /mingw|cygwin/i ? "make" : "nmake"
65
+
66
+ mkdir_p "lib/win32/ruby18"
67
+ mkdir_p "lib/win32/ruby19"
68
+
69
+ Dir.chdir('ext') do
70
+ # Ruby 1.8
71
+ sh "C:\\ruby187\\bin\\ruby extconf.rb"
72
+ sh "#{make}"
73
+ mv 'daemon.so', '../lib/win32/ruby18'
74
+ sh "#{make} distclean"
75
+
76
+ # Ruby 1.9
77
+ sh "C:\\ruby192\\bin\\ruby extconf.rb"
78
+ sh "#{make}"
79
+ mv 'daemon.so', '../lib/win32/ruby19'
80
+ end
81
+
82
+ File.open("lib/win32/daemon.rb", "w"){ |fh|
83
+ fh.puts "if RUBY_VERSION.to_f >= 1.9"
84
+ fh.puts " require 'win32/ruby19/daemon'"
85
+ fh.puts "else"
86
+ fh.puts " require 'win32/ruby18/daemon'"
87
+ fh.puts "end"
88
+ }
89
+
90
+ spec = eval(IO.read('win32-service.gemspec'))
91
+ spec.extensions = nil
92
+ spec.platform = Gem::Platform::CURRENT
93
+
94
+ spec.files = spec.files.reject{ |f| f.include?('ext') }
95
+
96
+ spec.files += [
97
+ 'lib/win32/daemon.rb',
98
+ 'lib/win32/ruby18/daemon.so',
99
+ 'lib/win32/ruby19/daemon.so'
100
+ ]
101
+
102
+ Gem::Builder.new(spec).build
103
+ end
104
+ end
105
+
106
+ namespace :example do
107
+ desc "Run the services example program."
108
+ task :services do
109
+ sh "ruby -Ilib examples/demo_services.rb"
110
+ end
73
111
  end
74
112
 
75
113
  namespace 'test' do
@@ -137,3 +175,5 @@ namespace 'test' do
137
175
  Rake.application[:clean].execute
138
176
  end
139
177
  end
178
+
179
+ task :default => 'test:all'
data/doc/daemon.txt CHANGED
@@ -1,156 +1,156 @@
1
1
  = Description
2
- The Daemon class is a wrapper class that allows you to run your code as a
3
- Windows service.
2
+ The Daemon class is a wrapper class that allows you to run your code as a
3
+ Windows service.
4
4
 
5
5
  = Synopsis
6
- class Daemon
7
- def service_main
8
- while running?
9
- sleep 3
10
- File.open("c:\\test.log", "a"){ |f| f.puts "service is running" }
11
- end
6
+ class Daemon
7
+ def service_main
8
+ while running?
9
+ sleep 3
10
+ File.open("c:\\test.log", "a"){ |f| f.puts "service is running" }
12
11
  end
13
- end
12
+ end
13
+ end
14
14
 
15
- Daemon.mainloop
15
+ Daemon.mainloop
16
16
 
17
- = Class Methods
17
+ = Singleton Methods
18
18
  Daemon.mainloop
19
- This is the method that actually puts your code into a loop and allows it
20
- to run as a service. The code that is actually run while in the mainloop
21
- is what you defined in the Daemon#service_main method.
19
+ This is the method that actually puts your code into a loop and allows it
20
+ to run as a service. The code that is actually run while in the mainloop
21
+ is what you defined in the Daemon#service_main method.
22
22
 
23
23
  = Instance Methods
24
24
  Daemon#running?
25
- Returns whether or not the daemon is running. This is just a shortcut
26
- for checking if the state is RUNNING, PAUSED or IDLE.
25
+ Returns whether or not the daemon is running. This is just a shortcut
26
+ for checking if the state is RUNNING, PAUSED or IDLE.
27
27
 
28
- This is typically used within your service_main method. See the
29
- demo_daemon.rb file in the 'examples' directory for an example of how it's
30
- used in practice.
28
+ This is typically used within your service_main method. See the
29
+ demo_daemon.rb file in the 'examples' directory for an example of how it's
30
+ used in practice.
31
31
 
32
32
  Daemon#service_init
33
- Any code defined defined within this method occurs before service_main is
34
- reached. Any initialization code that takes more than two seconds to
35
- execute should be placed here. Otherwise, your service may timeout when
36
- you try to start it.
33
+ Any code defined defined within this method occurs before service_main is
34
+ reached. Any initialization code that takes more than two seconds to
35
+ execute should be placed here. Otherwise, your service may timeout when
36
+ you try to start it.
37
37
 
38
38
  Daemon#service_main(*args)
39
- You are expected to define your own service_main() method. The code
40
- defined in this method is the code that will run while running as a
41
- service.
39
+ You are expected to define your own service_main() method. The code
40
+ defined in this method is the code that will run while running as a
41
+ service.
42
42
 
43
- Any +args+ passed to Service.start are passed to this method.
43
+ Any +args+ passed to Service.start are passed to this method.
44
44
 
45
45
  Daemon#state
46
- Returns the current state of the Daemon. For a list of valid states, see
47
- the Constants section below.
46
+ Returns the current state of the Daemon. For a list of valid states, see
47
+ the Constants section below.
48
48
 
49
49
  = Signal Event Hooks
50
- These methods are called if defined within your Daemon class, and the
51
- appropriate signal is received by your service.
50
+ These methods are called if defined within your Daemon class, and the
51
+ appropriate signal is received by your service.
52
52
 
53
53
  Daemon#service_stop
54
- Called if the service receives a SERVICE_CONTROL_STOP signal. This is
55
- what the Service.stop() method sends.
54
+ Called if the service receives a SERVICE_CONTROL_STOP signal. This is
55
+ what the Service.stop() method sends.
56
56
 
57
57
  Daemon#service_pause
58
- Called if the service receives a SERVICE_CONTROL_PAUSE signal. This is
59
- what the Service.pause() method sends.
58
+ Called if the service receives a SERVICE_CONTROL_PAUSE signal. This is
59
+ what the Service.pause() method sends.
60
60
 
61
61
  Daemon#service_resume
62
- Called if the service receives a SERVICE_CONTROL_CONTINUE signal. This
63
- is what the Service.resume() method sends.
62
+ Called if the service receives a SERVICE_CONTROL_CONTINUE signal. This
63
+ is what the Service.resume() method sends.
64
64
 
65
65
  Daemon#service_interrogate
66
- Called if the service receives a SERVICE_CONTROL_INTERROGATE signal. This
67
- notifies a service that it should report its current status information to
68
- the service control manager.
66
+ Called if the service receives a SERVICE_CONTROL_INTERROGATE signal. This
67
+ notifies a service that it should report its current status information to
68
+ the service control manager.
69
69
 
70
70
  Daemon#service_shutdown
71
- Called if the service receives a SERVICE_CONTROL_SHUTDOWN signal.
71
+ Called if the service receives a SERVICE_CONTROL_SHUTDOWN signal.
72
72
 
73
73
  Daemon#service_netbindadd
74
- Called if the service receives a SERVICE_CONTROL_NETBINDADD signal. This
75
- notifies a network service that there is a new component for binding.
74
+ Called if the service receives a SERVICE_CONTROL_NETBINDADD signal. This
75
+ notifies a network service that there is a new component for binding.
76
76
 
77
77
  Daemon#service_netbinddisable
78
- Called if the service receives a SERVICE_CONTROL_NETBINDDISABLE signal.
79
- This notifies a network service that one of its bindings has been
80
- disabled.
78
+ Called if the service receives a SERVICE_CONTROL_NETBINDDISABLE signal.
79
+ This notifies a network service that one of its bindings has been
80
+ disabled.
81
81
 
82
82
  Daemon#service_netbindenable
83
- Called if the service receives a SERVICE_CONTROL_NETBINDENABLE signal.
84
- This Notifies a network service that a disabled binding has been enabled.
83
+ Called if the service receives a SERVICE_CONTROL_NETBINDENABLE signal.
84
+ This Notifies a network service that a disabled binding has been enabled.
85
85
 
86
86
  Daemon#service_netbindremove
87
- Called if the service receives a SERVICE_CONTROL_NETBINDREMOVE signal.
88
- This notifies a network service that that a component for binding has
89
- been removed.
87
+ Called if the service receives a SERVICE_CONTROL_NETBINDREMOVE signal.
88
+ This notifies a network service that that a component for binding has
89
+ been removed.
90
90
 
91
91
  Daemon#service_paramchange
92
- Called if the service receives a SERVICE_CONTROL_PARAMCHANGE signal.
93
- This notifies a service that its startup parameters have changed.
92
+ Called if the service receives a SERVICE_CONTROL_PARAMCHANGE signal.
93
+ This notifies a service that its startup parameters have changed.
94
94
 
95
95
  = Constants
96
96
 
97
97
  === Service state constants
98
98
  Daemon::CONTINUE_PENDING
99
- The service continue is pending.
99
+ The service continue is pending.
100
100
 
101
101
  Daemon::PAUSE_PENDING
102
- The service pause is pending.
102
+ The service pause is pending.
103
103
 
104
104
  Daemon::PAUSED
105
- The service is paused (but not STOPPED).
105
+ The service is paused (but not STOPPED).
106
106
 
107
107
  Daemon::RUNNING
108
- The service is running.
108
+ The service is running.
109
109
 
110
110
  Daemon::START_PENDING
111
- The service is starting (but is not yet in a RUNNING state).
111
+ The service is starting (but is not yet in a RUNNING state).
112
112
 
113
113
  Daemon::STOP_PENDING
114
- The service is stopping (but is not yet in a STOPPED state).
114
+ The service is stopping (but is not yet in a STOPPED state).
115
115
 
116
116
  Daemon::STOPPED
117
- The service is not running.
117
+ The service is not running.
118
118
 
119
119
  Daemon::IDLE
120
- The service is running, in an idle state. This is a custom state that
121
- we added that gets around a thread blocking issue.
120
+ The service is running, in an idle state. This is a custom state that
121
+ we added that gets around a thread blocking issue.
122
122
 
123
123
  = Notes
124
- You must create a service before you can actually run it. Look in the
125
- examples directory for the files 'demo_daemon.rb' and 'demodaemon_ctl.rb'.
126
- They're small and straightforward examples of how to control, install and
127
- setup your own Daemon.
124
+ You must create a service before you can actually run it. Look in the
125
+ examples directory for the files 'demo_daemon.rb' and 'demodaemon_ctl.rb'.
126
+ They're small and straightforward examples of how to control, install and
127
+ setup your own Daemon.
128
128
 
129
129
  = Known Bugs
130
- None known. Please report any bugs you find on the Bug tracker at
131
- http://rubyforge.org/projects/win32utils.
130
+ None known. Please report any bugs you find on the Bug tracker at
131
+ http://rubyforge.org/projects/win32utils.
132
132
 
133
133
  = Future Plans
134
- Rewrite the Daemon class in pure Ruby.
134
+ Rewrite the Daemon class in pure Ruby.
135
135
 
136
- Suggestions welcome. Please log them on the Feature Request tracker at
137
- http://rubyforge.org/projects/win32utils
136
+ Suggestions welcome. Please log them on the Feature Request tracker at
137
+ http://rubyforge.org/projects/win32utils
138
138
 
139
139
  = Acknowledgements
140
- Many thanks go to Patrick Hurley for providing the fix for the thread
141
- blocking issue. Thanks also go to Kevin Burge for his patch that solved
142
- service responsiveness issues.
140
+ Many thanks go to Patrick Hurley for providing the fix for the thread
141
+ blocking issue. Thanks also go to Kevin Burge for his patch that solved
142
+ service responsiveness issues.
143
143
 
144
144
  = Copyright
145
- (C) 2003-2009 Daniel J. Berger, All Rights Reserved
145
+ (C) 2003-2011 Daniel J. Berger, All Rights Reserved
146
146
 
147
147
  = License
148
- Artistic 2.0
148
+ Artistic 2.0
149
149
 
150
150
  = Warranty
151
- This package is provided "as is" and without any express or
152
- implied warranties, including, without limitation, the implied
153
- warranties of merchantability and fitness for a particular purpose.
151
+ This package is provided "as is" and without any express or
152
+ implied warranties, including, without limitation, the implied
153
+ warranties of merchantability and fitness for a particular purpose.
154
154
 
155
155
  = Author(s)
156
156
  * Daniel J. Berger
data/doc/service.txt CHANGED
@@ -1,364 +1,363 @@
1
1
  = Description
2
- An interface for MS Windows Services.
2
+ An interface for MS Windows Services.
3
3
 
4
4
  = Prerequisites
5
- Ruby 1.8.0 or later.
5
+ Ruby 1.8.2 or later.
6
6
 
7
- This package is only supported for the Windows NT family of operating
8
- systems, e.g. 2000, XP, 2003, etc. It is NOT supported (and won't
9
- work) for any version of DOS or Windows 95/98/ME. It is also not
10
- supported on NT 4, as that platform is defunct.
7
+ This library is only supported for the Windows NT family of operating
8
+ systems, e.g. 2000, XP, 2003, etc. It is NOT supported (and won't
9
+ work) for any version of DOS or Windows 95/98/ME. It is also not
10
+ supported on NT 4, as that platform is defunct.
11
11
 
12
- It should work on Windows XP Home, but is not officially supported for
13
- that platform.
12
+ It should work on Windows XP Home, but is not officially supported for
13
+ that platform.
14
14
 
15
15
  = Synopsis
16
- require "win32/service"
17
- include Win32
18
-
19
- # Create a new service
20
- Service.create(
21
- :service_name => 'some_service',
22
- :service_type => Service::WIN32_OWN_PROCESS,
23
- :description => 'A custom service I wrote just for fun'
24
- :start_type => Service::AUTO_START,
25
- :error_control => Service::ERROR_NORMAL,
26
- :binary_path_name => 'C:\path\to\some_service.exe',
27
- :load_order_group => 'Network',
28
- :dependencies => ['W32Time','Schedule']
29
- :service_start_name => 'SomeDomain\\User',
30
- :password => 'XXXXXXX',
31
- :display_name => 'This is some service',
32
- )
33
-
34
- # Configure a service that already exists
35
- Service.configure(:display_name => "My Bar Service")
36
-
37
- Service.start("foo")
38
- Service.pause("foo")
39
- Service.resume("foo")
40
- Service.stop("foo")
41
-
42
- Service.delete("foo")
43
-
44
- Service.get_display_name("Schedule") # "Task Scheduler"
45
- Service.get_service_name("ClipBook") # "ClipSrv"
16
+ require "win32/service"
17
+ include Win32
18
+
19
+ # Create a new service
20
+ Service.create(
21
+ :service_name => 'some_service',
22
+ :service_type => Service::WIN32_OWN_PROCESS,
23
+ :description => 'A custom service I wrote just for fun'
24
+ :start_type => Service::AUTO_START,
25
+ :error_control => Service::ERROR_NORMAL,
26
+ :binary_path_name => 'C:\path\to\some_service.exe',
27
+ :load_order_group => 'Network',
28
+ :dependencies => ['W32Time','Schedule']
29
+ :service_start_name => 'SomeDomain\\User',
30
+ :password => 'XXXXXXX',
31
+ :display_name => 'This is some service',
32
+ )
33
+
34
+ # Configure a service that already exists
35
+ Service.configure(:display_name => "My Bar Service")
36
+
37
+ Service.start("foo")
38
+ Service.pause("foo")
39
+ Service.resume("foo")
40
+ Service.stop("foo")
41
+
42
+ Service.delete("foo")
46
43
 
47
- Service.status('W32Time') => <struct Struct::ServiceStatus ...>
44
+ Service.get_display_name("Schedule") # "Task Scheduler"
45
+ Service.get_service_name("ClipBook") # "ClipSrv"
46
+
47
+ Service.status('W32Time') => <struct Struct::ServiceStatus ...>
48
48
 
49
- # Enumerate over all services, inspecting each struct
50
- Service.services{ |s|
51
- p s
52
- puts
53
- }
49
+ # Enumerate over all services, inspecting each struct
50
+ Service.services{ |s|
51
+ puts s.inspect
52
+ }
54
53
 
55
54
  = Class Methods
56
55
  Service.new(options={})
57
- Creates a new service. The +options+ parameter is a hash that can
58
- contain any of the following parameters, and their default values:
56
+ Creates a new service. The +options+ parameter is a hash that can
57
+ contain any of the following parameters, and their default values:
59
58
 
60
- * service_name => nil (mandatory)
61
- * host => nil
62
- * display_name => service_name
63
- * desired_access => Service::ALL_ACCESS
64
- * service_type => Service::WIN32_OWN_PROCESS | Service::INTERACTIVE_PROCESS
65
- * start_type => Service::DEMAND_START
66
- * error_control => Service::ERROR_NORMAL
67
- * binary_path_name => nil
68
- * load_order_group => nil
69
- * dependencies => nil
70
- * service_start_name => nil
71
- * password => nil
72
- * description => nil
59
+ KEY DEFAULT
60
+ * service_name => nil (mandatory)
61
+ * host => nil
62
+ * display_name => service_name
63
+ * desired_access => Service::ALL_ACCESS
64
+ * service_type => Service::WIN32_OWN_PROCESS|Service::INTERACTIVE_PROCESS
65
+ * start_type => Service::DEMAND_START
66
+ * error_control => Service::ERROR_NORMAL
67
+ * binary_path_name => nil
68
+ * load_order_group => nil
69
+ * dependencies => nil
70
+ * service_start_name => nil
71
+ * password => nil
72
+ * description => nil
73
73
 
74
74
  Service.configure(options={})
75
- Configures an existing service. The +options+ parameter is a hash that can
76
- contain any of the following parameters:
75
+ Configures an existing service. The +options+ parameter is a hash that can
76
+ contain any of the following parameters:
77
77
 
78
- * service_name (mandatory)
79
- * host
80
- * service_type
81
- * start_type
82
- * error_control
83
- * binary_path_name
84
- * load_order_group
85
- * dependencies
86
- * service_start_name
87
- * password (used with service_start_name)
88
- * display_name
89
- * description
78
+ * service_name (mandatory)
79
+ * host
80
+ * service_type
81
+ * start_type
82
+ * error_control
83
+ * binary_path_name
84
+ * load_order_group
85
+ * dependencies
86
+ * service_start_name
87
+ * password (used with service_start_name)
88
+ * display_name
89
+ * description
90
90
 
91
91
  Service.config_info(service, host=nil)
92
- Returns a ServiceConfigInfo struct containing the configuration information
93
- about +service+ on +host+, or the local host if no host is specified.
92
+ Returns a ServiceConfigInfo struct containing the configuration information
93
+ about +service+ on +host+, or the local host if no host is specified.
94
94
 
95
95
  Service.create
96
- Alias for Service.new
96
+ Alias for Service.new
97
97
 
98
98
  Service.delete(service, host=nil)
99
- Deletes the specified +service+ on +host+. If no host is given,
100
- then it deletes it on the local machine.
99
+ Deletes the specified +service+ on +host+. If no host is given,
100
+ then it deletes it on the local machine.
101
101
 
102
102
  Service.exists?(service)
103
- Returns true if the specified service exists, false otherwise.
103
+ Returns true if the specified service exists, false otherwise.
104
104
 
105
105
  Service.pause(service, host=nil)
106
- Pauses the specified +service+ on +host+, or the local machine if
107
- no host is provided.
106
+ Pauses the specified +service+ on +host+, or the local machine if
107
+ no host is provided.
108
108
 
109
109
  Service.resume(service, host=nil)
110
- Resumes the specified +service+ on +host+, or the local machine if
111
- no host is specified.
110
+ Resumes the specified +service+ on +host+, or the local machine if
111
+ no host is specified.
112
112
 
113
113
  Service.services(host=nil, group=nil){ |struct| ... }
114
- Enumerates over a list of service types on host, or the local
115
- machine if no host is specified, yielding a Win32Service struct for each
116
- service.
117
-
118
- If a 'group' is specified, then only those services that belong to
119
- that group are enumerated. If an empty string is provided, then only
120
- services that do not belong to any group are enumerated. If this parameter
121
- is nil, group membership is ignored and all services are enumerated.
114
+ Enumerates over a list of service types on host, or the local
115
+ machine if no host is specified, yielding a Win32Service struct for each
116
+ service.
117
+
118
+ If a 'group' is specified, then only those services that belong to
119
+ that group are enumerated. If an empty string is provided, then only
120
+ services that do not belong to any group are enumerated. If this parameter
121
+ is nil, group membership is ignored and all services are enumerated.
122
122
 
123
- The 'group' option is only available on Windows 2000 or later, and only
124
- if compiled with VC++ 7.0 or later, or the .NET SDK. The Win32Service
125
- struct contains the following members:
123
+ The 'group' option is only available on Windows 2000 or later, and only
124
+ if compiled with VC++ 7.0 or later, or the .NET SDK. The Win32Service
125
+ struct contains the following members:
126
126
 
127
- * service_name
128
- * display_name
129
- * service_type
130
- * current_state
131
- * controls_accepted
132
- * win32_exit_code
133
- * service_specific_exit_code
134
- * check_point
135
- * wait_hint
136
- * binary_path_name
137
- * start_type
138
- * error_control
139
- * load_order_group
140
- * tag_id
141
- * start_name
142
- * dependencies
143
- * description
144
- * interactive?
145
- * pid (Win2k or later)
146
- * service_flags (Win2k or later)
127
+ * service_name
128
+ * display_name
129
+ * service_type
130
+ * current_state
131
+ * controls_accepted
132
+ * win32_exit_code
133
+ * service_specific_exit_code
134
+ * check_point
135
+ * wait_hint
136
+ * binary_path_name
137
+ * start_type
138
+ * error_control
139
+ * load_order_group
140
+ * tag_id
141
+ * start_name
142
+ * dependencies
143
+ * description
144
+ * interactive?
145
+ * pid (Win2k or later)
146
+ * service_flags (Win2k or later)
147
147
 
148
- Note that the 'pid' and 'service_flags' members are only available on
149
- Windows 2000 or later, and only if built with VC++ 7.0 or later (or the
150
- .NET SDK).
148
+ Note that the 'pid' and 'service_flags' members are only available on
149
+ Windows 2000 or later, and only if built with VC++ 7.0 or later (or the
150
+ .NET SDK).
151
151
 
152
152
  Service.start(service, host=nil, *args)
153
- Starts the specified +service+ on +host+, or the local machine if no
154
- host is specified. Any +args+ passed here are passed as start parameters
155
- to the service.
156
-
153
+ Starts the specified +service+ on +host+, or the local machine if no
154
+ host is specified. Any +args+ passed here are passed as start parameters
155
+ to the service.
156
+
157
157
  Service.status(service)
158
- Returns a Win32ServiceStatus struct for the specified service (or
159
- raises a Win32::ServiceError if not found). The Win32ServiceStatus
160
- struct contains the following members.
161
-
162
- * service_type
163
- * current_state
164
- * controls_accepted
165
- * win32_exit_code
166
- * service_specific_exit_code
167
- * check_point
168
- * wait_hint
169
- * interactive?
158
+ Returns a Win32ServiceStatus struct for the specified service (or
159
+ raises a Win32::ServiceError if not found). The Win32ServiceStatus
160
+ struct contains the following members.
161
+
162
+ * service_type
163
+ * current_state
164
+ * controls_accepted
165
+ * win32_exit_code
166
+ * service_specific_exit_code
167
+ * check_point
168
+ * wait_hint
169
+ * interactive?
170
170
 
171
171
  Service.stop(service, host=nil)
172
- Stops the specified +service+ on +host+, or the local machine if no
173
- host is specified.
172
+ Stops the specified +service+ on +host+, or the local machine if no
173
+ host is specified.
174
174
 
175
175
  = Create and configure options
176
176
  binary_path_name
177
- The binary to be used for the service. The path must be the fully
178
- qualified path name. A path that contains a space must be quoted so that
179
- it is correctly interpreted. The path may also include arguments to the
180
- service entry point (typically the 'main' function).
177
+ The binary to be used for the service. The path must be the fully
178
+ qualified path name. A path that contains a space must be quoted so that
179
+ it is correctly interpreted. The path may also include arguments to the
180
+ service entry point (typically the 'main' function).
181
181
 
182
182
  dependencies
183
- Any dependencies the service has in order to run. This can be a string
184
- or an array of strings.
183
+ Any dependencies the service has in order to run. This can be a string
184
+ or an array of strings.
185
185
 
186
186
  description
187
- A text string describing the service.
187
+ A text string describing the service.
188
188
 
189
189
  display_name
190
- The display name to be used by user interface programs to identify the
191
- service. The string has a maximum length of 256 characters. Case
192
- sensitivity is preserved.
190
+ The display name to be used by user interface programs to identify the
191
+ service. The string has a maximum length of 256 characters. Case
192
+ sensitivity is preserved.
193
193
 
194
- The default is to set the display name to the same string as the
195
- service name.
194
+ The default is to set the display name to the same string as the
195
+ service name.
196
196
 
197
197
  error_control
198
- The error control for the service. The default is Service::ERROR_NORMAL.
199
-
200
- See the "Error Control Contants" section for available options and their
201
- meanings.
198
+ The error control for the service. The default is Service::ERROR_NORMAL.
199
+
200
+ See the "Error Control Contants" section for available options and their
201
+ meanings.
202
202
 
203
203
  load_order_group
204
- The load order group, a string that names the load ordering group of
205
- which this service is a member. The default is nil.
204
+ The load order group, a string that names the load ordering group of
205
+ which this service is a member. The default is nil.
206
206
 
207
207
  password
208
- Sets the passsword to the account name specified in the Service#start_name
209
- method. By default, this value is set to nil, which is appropriate if
210
- the account has no password or if the service runs in the
211
- 'LocalService', 'NetworkService', or 'LocalSystem' account.
208
+ Sets the passsword to the account name specified in the Service#start_name
209
+ method. By default, this value is set to nil, which is appropriate if
210
+ the account has no password or if the service runs in the
211
+ 'LocalService', 'NetworkService', or 'LocalSystem' account.
212
212
 
213
- Note that passwords are ignored for driver services.
213
+ Note that passwords are ignored for driver services.
214
214
 
215
215
  service_name
216
- The service name for the service. This value must be set in order
217
- to create a service. The string has a maximum length of 256 characters.
216
+ The service name for the service. This value must be set in order
217
+ to create a service. The string has a maximum length of 256 characters.
218
218
 
219
219
  service_type
220
- The service type for the service. The default is
221
- Service::WIN32_OWN_PROCESS | Service::INTERACTIVE_PROCESS.
220
+ The service type for the service. The default is
221
+ Service::WIN32_OWN_PROCESS | Service::INTERACTIVE_PROCESS.
222
222
 
223
- See the "Service Type Contants" section for available options and their
224
- meanings.
223
+ See the "Service Type Contants" section for available options and their
224
+ meanings.
225
225
 
226
226
  start_name
227
- Sets the name of the account under which the service should run.
228
- By default the 'LocalSystem' account is used.
227
+ Sets the name of the account under which the service should run.
228
+ By default the 'LocalSystem' account is used.
229
229
 
230
230
  start_type
231
- The start type for the service. The default is Service::DEMAND_START.
231
+ The start type for the service. The default is Service::DEMAND_START.
232
232
 
233
- See the "Start Type Contants" section for available options and their
234
- meanings.
233
+ See the "Start Type Contants" section for available options and their
234
+ meanings.
235
235
 
236
236
  = Constants
237
237
 
238
238
  === Standard Constants
239
239
  VERSION
240
- The current version number of this package, returned as a string.
240
+ The current version number of this package, returned as a string.
241
241
 
242
242
  === Desired Access Constants
243
243
  Service::MANAGER_ALL_ACCESS
244
- Includes STANDARD_RIGHTS_REQUIRED, in addition to all access rights
245
- in the table.
244
+ Includes STANDARD_RIGHTS_REQUIRED, in addition to all access rights
245
+ in the table.
246
246
 
247
247
  Service::MANAGER_CREATE_SERVICE
248
- Required to call the CreateService function to create a service object
249
- and add it to the database.
248
+ Required to call the CreateService function to create a service object
249
+ and add it to the database.
250
250
 
251
251
  Service::MANAGER_CONNECT
252
- Required to connect to the service control manager.
252
+ Required to connect to the service control manager.
253
253
 
254
254
  Service::MANAGER_ENUMERATE_SERVICE
255
- Required to call the EnumServicesStatus function to list the services
256
- that are in the database.
255
+ Required to call the EnumServicesStatus function to list the services
256
+ that are in the database.
257
257
 
258
258
  Service::MANAGER_LOCK
259
- Required to call the LockServiceDatabase function to acquire a lock on the
260
- database.
259
+ Required to call the LockServiceDatabase function to acquire a lock on the
260
+ database.
261
261
 
262
262
  Service::MANAGER_BOOT_CONFIG
263
- Required to call the NotifyBootConfigStatus() (internal) function. Not
264
- defined with all compilers.
263
+ Required to call the NotifyBootConfigStatus() (internal) function. Not
264
+ defined with all compilers.
265
265
 
266
266
  Service::MANAGER_QUERY_LOCK_STATUS
267
- Required to call the QueryServiceLockStatus() (internal) function to
268
- retrieve the lock status information for the database.
267
+ Required to call the QueryServiceLockStatus() (internal) function to
268
+ retrieve the lock status information for the database.
269
269
 
270
270
  === Service Type Constants
271
271
  Service::FILE_SYSTEM_DRIVER
272
- File system driver service.
272
+ File system driver service.
273
273
 
274
274
  Service::KERNEL_DRIVER
275
- Driver service.
275
+ Driver service.
276
276
 
277
277
  Service::WIN32_OWN_PROCESS
278
- Service that runs in its own process.
278
+ Service that runs in its own process.
279
279
 
280
280
  Service::WIN32_SHARE_PROCESS
281
- Service that shares a process with one or more other services.
281
+ Service that shares a process with one or more other services.
282
282
 
283
283
  Service::INTERACTIVE_PROCESS
284
- The service can interact with the desktop. This can only be used if
285
- either SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS is
286
- specified as well, and the service is running in the context of the
287
- LocalSystem account (which is the default for this module, btw).
284
+ The service can interact with the desktop. This can only be used if
285
+ either SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS is
286
+ specified as well, and the service is running in the context of the
287
+ LocalSystem account (which is the default for this module, btw).
288
288
 
289
289
  === Start Type Constants
290
290
  Service::AUTO_START
291
- A service started automatically by the service control manager during
292
- system startup.
291
+ A service started automatically by the service control manager during
292
+ system startup.
293
293
 
294
294
  Service::BOOT_START
295
- A device driver started by the system loader. This value is valid only
296
- for driver services.
295
+ A device driver started by the system loader. This value is valid only
296
+ for driver services.
297
297
 
298
298
  Service::DEMAND_START
299
- A service started by the service control manager when a process calls
300
- the StartService() function.
299
+ A service started by the service control manager when a process calls
300
+ the StartService() function.
301
301
 
302
302
  Service::DISABLED
303
- A service that cannot be started. Attempts to start the service result
304
- in an error.
303
+ A service that cannot be started. Attempts to start the service result
304
+ in an error.
305
305
 
306
306
  Service::SYSTEM_START
307
- A device driver started by the IoInitSystem() function. This value is
308
- valid only for driver services.
307
+ A device driver started by the IoInitSystem() function. This value is
308
+ valid only for driver services.
309
309
 
310
310
  === Error Control Constants
311
311
  Service::ERROR_IGNORE
312
- The startup program logs the error but continues the startup operation.
312
+ The startup program logs the error but continues the startup operation.
313
313
 
314
314
  Service::ERROR_NORMAL
315
- The startup program logs the error and puts up a message box pop-up but
316
- continues the startup operation.
315
+ The startup program logs the error and puts up a message box pop-up but
316
+ continues the startup operation.
317
317
 
318
318
  Service::ERROR_SEVERE
319
- The startup program logs the error. If the last-known-good configuration
320
- is being started, the startup operation continues. Otherwise, the system
321
- is restarted with the last-known-good configuration.
322
-
319
+ The startup program logs the error. If the last-known-good configuration
320
+ is being started, the startup operation continues. Otherwise, the system
321
+ is restarted with the last-known-good configuration.
322
+
323
323
  Service::ERROR_CRITICAL
324
- The startup program logs the error, if possible. If the last-known-good
325
- configuration is being started the startup operation fails. Otherwise,
326
- the system is restarted with the last-known-good configuration.
324
+ The startup program logs the error, if possible. If the last-known-good
325
+ configuration is being started the startup operation fails. Otherwise,
326
+ the system is restarted with the last-known-good configuration.
327
327
 
328
328
  = Notes
329
- See the MSDN API with regards to CreateService(), etc at
330
- http://www.msdn.com
329
+ See the MSDN API with regards to CreateService(), etc at http://www.msdn.com.
331
330
 
332
- Some API ideas taken (or not) from both Python's win32serviceutil.py and
333
- Perl's Win32::Service module.
331
+ Some API ideas taken (or not) from both Python's win32serviceutil.py and
332
+ Perl's Win32::Service module.
334
333
 
335
- I don't truly understand how to allow a tag_id in the create_service()
336
- method, so for now it's set to NULL automatically. Suggestions welcome.
334
+ I don't truly understand how to allow a tag_id in the create_service()
335
+ method, so for now it's set to NULL automatically. Suggestions welcome.
337
336
 
338
337
  = Known Bugs
339
- There may be a failure in the test suite if the W32Time dependency is
340
- not started.
338
+ There may be a failure in the test suite if the W32Time dependency is
339
+ not started.
341
340
 
342
- If you find any bugs please log them on the bug tracker. You can find it
343
- on the project page at http://www.rubyforge.org/projects/win32utils.
341
+ If you find any bugs please log them on the bug tracker. You can find it
342
+ on the project page at http://www.rubyforge.org/projects/win32utils.
344
343
 
345
344
  = Acknowledgements
346
- Many thanks go to Patrick Hurley for providing the fix for the thread
347
- blocking issue. Thanks also go to Kevin Burge for his patch that solved
348
- service responsiveness issues.
345
+ Many thanks go to Patrick Hurley for providing the fix for the thread
346
+ blocking issue. Thanks also go to Kevin Burge for his patch that solved
347
+ service responsiveness issues.
349
348
 
350
349
  = Future Plans
351
- Add Tag_ID support.
352
- Add ability to create or modify service failure actions.
353
- Use RegisterServiceCtrlHandlerEx().
350
+ Add Tag_ID support.
351
+ Add ability to create or modify service failure actions.
352
+ Use RegisterServiceCtrlHandlerEx().
354
353
 
355
354
  = Copyright
356
- (C) 2003-2010, Daniel J. Berger, All Rights Reserved
355
+ (C) 2003-2011, Daniel J. Berger, All Rights Reserved
357
356
 
358
357
  = Warranty
359
- This package is provided "as is" and without any express or
360
- implied warranties, including, without limitation, the implied
361
- warranties of merchantability and fitness for a particular purpose.
358
+ This package is provided "as is" and without any express or
359
+ implied warranties, including, without limitation, the implied
360
+ warranties of merchantability and fitness for a particular purpose.
362
361
 
363
362
  == Author(s)
364
363
  * Daniel J. Berger