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 +7 -0
- data/README +4 -7
- data/Rakefile +73 -33
- data/doc/daemon.txt +79 -79
- data/doc/service.txt +230 -231
- data/examples/demo_daemon.rb +82 -76
- data/examples/demo_services.rb +12 -5
- data/ext/extconf.rb +4 -0
- data/ext/win32/daemon.c +359 -358
- data/lib/win32/service.rb +5 -2
- data/test/test_win32_daemon.rb +11 -8
- data/test/test_win32_service.rb +3 -3
- data/win32-service.gemspec +2 -3
- metadata +40 -16
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
|
-
|
|
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-
|
|
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
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
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
|
|
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
|
-
|
|
3
|
-
|
|
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
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
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
|
-
|
|
12
|
+
end
|
|
13
|
+
end
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
Daemon.mainloop
|
|
16
16
|
|
|
17
|
-
=
|
|
17
|
+
= Singleton Methods
|
|
18
18
|
Daemon.mainloop
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
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
|
-
|
|
26
|
-
|
|
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
|
-
|
|
29
|
-
|
|
30
|
-
|
|
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
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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
|
-
|
|
40
|
-
|
|
41
|
-
|
|
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
|
-
|
|
43
|
+
Any +args+ passed to Service.start are passed to this method.
|
|
44
44
|
|
|
45
45
|
Daemon#state
|
|
46
|
-
|
|
47
|
-
|
|
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
|
-
|
|
51
|
-
|
|
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
|
-
|
|
55
|
-
|
|
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
|
-
|
|
59
|
-
|
|
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
|
-
|
|
63
|
-
|
|
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
|
-
|
|
67
|
-
|
|
68
|
-
|
|
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
|
-
|
|
71
|
+
Called if the service receives a SERVICE_CONTROL_SHUTDOWN signal.
|
|
72
72
|
|
|
73
73
|
Daemon#service_netbindadd
|
|
74
|
-
|
|
75
|
-
|
|
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
|
-
|
|
79
|
-
|
|
80
|
-
|
|
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
|
-
|
|
84
|
-
|
|
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
|
-
|
|
88
|
-
|
|
89
|
-
|
|
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
|
-
|
|
93
|
-
|
|
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
|
-
|
|
99
|
+
The service continue is pending.
|
|
100
100
|
|
|
101
101
|
Daemon::PAUSE_PENDING
|
|
102
|
-
|
|
102
|
+
The service pause is pending.
|
|
103
103
|
|
|
104
104
|
Daemon::PAUSED
|
|
105
|
-
|
|
105
|
+
The service is paused (but not STOPPED).
|
|
106
106
|
|
|
107
107
|
Daemon::RUNNING
|
|
108
|
-
|
|
108
|
+
The service is running.
|
|
109
109
|
|
|
110
110
|
Daemon::START_PENDING
|
|
111
|
-
|
|
111
|
+
The service is starting (but is not yet in a RUNNING state).
|
|
112
112
|
|
|
113
113
|
Daemon::STOP_PENDING
|
|
114
|
-
|
|
114
|
+
The service is stopping (but is not yet in a STOPPED state).
|
|
115
115
|
|
|
116
116
|
Daemon::STOPPED
|
|
117
|
-
|
|
117
|
+
The service is not running.
|
|
118
118
|
|
|
119
119
|
Daemon::IDLE
|
|
120
|
-
|
|
121
|
-
|
|
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
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
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
|
-
|
|
131
|
-
|
|
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
|
-
|
|
134
|
+
Rewrite the Daemon class in pure Ruby.
|
|
135
135
|
|
|
136
|
-
|
|
137
|
-
|
|
136
|
+
Suggestions welcome. Please log them on the Feature Request tracker at
|
|
137
|
+
http://rubyforge.org/projects/win32utils
|
|
138
138
|
|
|
139
139
|
= Acknowledgements
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
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
|
-
|
|
145
|
+
(C) 2003-2011 Daniel J. Berger, All Rights Reserved
|
|
146
146
|
|
|
147
147
|
= License
|
|
148
|
-
|
|
148
|
+
Artistic 2.0
|
|
149
149
|
|
|
150
150
|
= Warranty
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
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
|
-
|
|
2
|
+
An interface for MS Windows Services.
|
|
3
3
|
|
|
4
4
|
= Prerequisites
|
|
5
|
-
|
|
5
|
+
Ruby 1.8.2 or later.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
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
|
-
|
|
13
|
-
|
|
12
|
+
It should work on Windows XP Home, but is not officially supported for
|
|
13
|
+
that platform.
|
|
14
14
|
|
|
15
15
|
= Synopsis
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
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
|
-
|
|
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
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
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
|
-
|
|
58
|
-
|
|
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
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
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
|
-
|
|
76
|
-
|
|
75
|
+
Configures an existing service. The +options+ parameter is a hash that can
|
|
76
|
+
contain any of the following parameters:
|
|
77
77
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
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
|
-
|
|
93
|
-
|
|
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
|
-
|
|
96
|
+
Alias for Service.new
|
|
97
97
|
|
|
98
98
|
Service.delete(service, host=nil)
|
|
99
|
-
|
|
100
|
-
|
|
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
|
-
|
|
103
|
+
Returns true if the specified service exists, false otherwise.
|
|
104
104
|
|
|
105
105
|
Service.pause(service, host=nil)
|
|
106
|
-
|
|
107
|
-
|
|
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
|
-
|
|
111
|
-
|
|
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
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
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
|
-
|
|
124
|
-
|
|
125
|
-
|
|
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
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
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
|
-
|
|
149
|
-
|
|
150
|
-
|
|
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
|
-
|
|
154
|
-
|
|
155
|
-
|
|
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
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
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
|
-
|
|
173
|
-
|
|
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
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
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
|
-
|
|
184
|
-
|
|
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
|
-
|
|
187
|
+
A text string describing the service.
|
|
188
188
|
|
|
189
189
|
display_name
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
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
|
-
|
|
195
|
-
|
|
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
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
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
|
-
|
|
205
|
-
|
|
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
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
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
|
-
|
|
213
|
+
Note that passwords are ignored for driver services.
|
|
214
214
|
|
|
215
215
|
service_name
|
|
216
|
-
|
|
217
|
-
|
|
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
|
-
|
|
221
|
-
|
|
220
|
+
The service type for the service. The default is
|
|
221
|
+
Service::WIN32_OWN_PROCESS | Service::INTERACTIVE_PROCESS.
|
|
222
222
|
|
|
223
|
-
|
|
224
|
-
|
|
223
|
+
See the "Service Type Contants" section for available options and their
|
|
224
|
+
meanings.
|
|
225
225
|
|
|
226
226
|
start_name
|
|
227
|
-
|
|
228
|
-
|
|
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
|
-
|
|
231
|
+
The start type for the service. The default is Service::DEMAND_START.
|
|
232
232
|
|
|
233
|
-
|
|
234
|
-
|
|
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
|
-
|
|
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
|
-
|
|
245
|
-
|
|
244
|
+
Includes STANDARD_RIGHTS_REQUIRED, in addition to all access rights
|
|
245
|
+
in the table.
|
|
246
246
|
|
|
247
247
|
Service::MANAGER_CREATE_SERVICE
|
|
248
|
-
|
|
249
|
-
|
|
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
|
-
|
|
252
|
+
Required to connect to the service control manager.
|
|
253
253
|
|
|
254
254
|
Service::MANAGER_ENUMERATE_SERVICE
|
|
255
|
-
|
|
256
|
-
|
|
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
|
-
|
|
260
|
-
|
|
259
|
+
Required to call the LockServiceDatabase function to acquire a lock on the
|
|
260
|
+
database.
|
|
261
261
|
|
|
262
262
|
Service::MANAGER_BOOT_CONFIG
|
|
263
|
-
|
|
264
|
-
|
|
263
|
+
Required to call the NotifyBootConfigStatus() (internal) function. Not
|
|
264
|
+
defined with all compilers.
|
|
265
265
|
|
|
266
266
|
Service::MANAGER_QUERY_LOCK_STATUS
|
|
267
|
-
|
|
268
|
-
|
|
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
|
-
|
|
272
|
+
File system driver service.
|
|
273
273
|
|
|
274
274
|
Service::KERNEL_DRIVER
|
|
275
|
-
|
|
275
|
+
Driver service.
|
|
276
276
|
|
|
277
277
|
Service::WIN32_OWN_PROCESS
|
|
278
|
-
|
|
278
|
+
Service that runs in its own process.
|
|
279
279
|
|
|
280
280
|
Service::WIN32_SHARE_PROCESS
|
|
281
|
-
|
|
281
|
+
Service that shares a process with one or more other services.
|
|
282
282
|
|
|
283
283
|
Service::INTERACTIVE_PROCESS
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
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
|
-
|
|
292
|
-
|
|
291
|
+
A service started automatically by the service control manager during
|
|
292
|
+
system startup.
|
|
293
293
|
|
|
294
294
|
Service::BOOT_START
|
|
295
|
-
|
|
296
|
-
|
|
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
|
-
|
|
300
|
-
|
|
299
|
+
A service started by the service control manager when a process calls
|
|
300
|
+
the StartService() function.
|
|
301
301
|
|
|
302
302
|
Service::DISABLED
|
|
303
|
-
|
|
304
|
-
|
|
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
|
-
|
|
308
|
-
|
|
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
|
-
|
|
312
|
+
The startup program logs the error but continues the startup operation.
|
|
313
313
|
|
|
314
314
|
Service::ERROR_NORMAL
|
|
315
|
-
|
|
316
|
-
|
|
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
|
-
|
|
320
|
-
|
|
321
|
-
|
|
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
|
-
|
|
325
|
-
|
|
326
|
-
|
|
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
|
-
|
|
330
|
-
http://www.msdn.com
|
|
329
|
+
See the MSDN API with regards to CreateService(), etc at http://www.msdn.com.
|
|
331
330
|
|
|
332
|
-
|
|
333
|
-
|
|
331
|
+
Some API ideas taken (or not) from both Python's win32serviceutil.py and
|
|
332
|
+
Perl's Win32::Service module.
|
|
334
333
|
|
|
335
|
-
|
|
336
|
-
|
|
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
|
-
|
|
340
|
-
|
|
338
|
+
There may be a failure in the test suite if the W32Time dependency is
|
|
339
|
+
not started.
|
|
341
340
|
|
|
342
|
-
|
|
343
|
-
|
|
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
|
-
|
|
347
|
-
|
|
348
|
-
|
|
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
|
-
|
|
352
|
-
|
|
353
|
-
|
|
350
|
+
Add Tag_ID support.
|
|
351
|
+
Add ability to create or modify service failure actions.
|
|
352
|
+
Use RegisterServiceCtrlHandlerEx().
|
|
354
353
|
|
|
355
354
|
= Copyright
|
|
356
|
-
|
|
355
|
+
(C) 2003-2011, Daniel J. Berger, All Rights Reserved
|
|
357
356
|
|
|
358
357
|
= Warranty
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
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
|