win32-service 0.5.2-mswin32
Sign up to get free protection for your applications and to get access to all the features.
- data/CHANGES +174 -0
- data/MANIFEST +16 -0
- data/README +46 -0
- data/doc/daemon.txt +160 -0
- data/doc/service.txt +382 -0
- data/lib/win32/service.c +2131 -0
- data/lib/win32/service.h +416 -0
- data/lib/win32/service.so +0 -0
- data/test/tc_daemon.rb +59 -0
- data/test/tc_service.rb +406 -0
- metadata +59 -0
data/CHANGES
ADDED
@@ -0,0 +1,174 @@
|
|
1
|
+
== 0.5.2 - 25-Nov-2006
|
2
|
+
* Fixed a bug in the Daemon class where the service event handling methods
|
3
|
+
(most notably service_stop) did not work properly due to thread blocking
|
4
|
+
issues. Many thanks go to Patrick Hurley for the patch.
|
5
|
+
* Added the Daemon#running? method as helper method for your service_main
|
6
|
+
method.
|
7
|
+
* The 'interactive?' struct member is now just 'interactive'. This was
|
8
|
+
supposed to have been in the last release but was somehow missed. Sorry.
|
9
|
+
* Scrapped the old daemon_test.rb file and split it into two new files -
|
10
|
+
tdaemon.rb and tdaemon_ctl.rb. In the process a few bugs were fixed.
|
11
|
+
* Added a gemspec.
|
12
|
+
* Documentation and test suite updates.
|
13
|
+
|
14
|
+
== 0.5.1 - 18-Jun-2006
|
15
|
+
* Added the Service.open method.
|
16
|
+
* The Service.new method now accepts a block, and automatically closes itself
|
17
|
+
at the end of the block.
|
18
|
+
* Fixed in a bug in the Service.create method where setting dependencies
|
19
|
+
was not working properly. Thanks go to Scott Harper for the spot.
|
20
|
+
* The 'interactive?' struct member is now just 'interactive' since Ruby no
|
21
|
+
longer supports question marks in struct member names. UGH.
|
22
|
+
* The block for Service#configure_service is no longer optional.
|
23
|
+
* Replaced ClipSrv with W32Time for most of the test methods in tc_service.rb
|
24
|
+
because it had a dependency that is disabled on most systems.
|
25
|
+
* Added a tweak to the extconf.rb file to help with the test suite.
|
26
|
+
* Some documentation updates and corrections.
|
27
|
+
|
28
|
+
== 0.5.0 - 26-Nov-2005
|
29
|
+
* Added a service_init hook, and (internally) altered the way the service
|
30
|
+
starts. This was done to deal with services that need to perform any
|
31
|
+
initialization in the Daemon itself before the service starts. Previously
|
32
|
+
this would result in the service timing out during startup.
|
33
|
+
|
34
|
+
Thanks go to Jamey Cribbs for spotting the problem.
|
35
|
+
|
36
|
+
* Modified the Daemon example, adding a service_init hook that does about 10
|
37
|
+
seconds worth of initialization before finally starting. See the comments
|
38
|
+
in examples\daemon_test.rb for more information.
|
39
|
+
* Minor test and README changes.
|
40
|
+
|
41
|
+
== 0.4.6 - 24-May-2005
|
42
|
+
* Fixed an initialization bug that could cause Daemons to fail unless the
|
43
|
+
win32-service package was the last package require'd.
|
44
|
+
* Altered the Service.start method. It now takes any number of arguments
|
45
|
+
(after the service and host name). These arguments are passed to the
|
46
|
+
service's Service_Main() function.
|
47
|
+
* The Service.services method now returns an Array of ServiceStruct's in
|
48
|
+
non-block form.
|
49
|
+
* The Service.start, Service.pause, Service.resume, Service.stop and
|
50
|
+
Service.delete methods now return the class (self), not 'true'.
|
51
|
+
* Added the ability to add or configure the service description in
|
52
|
+
Service#create_service or Service#configure, respectively.
|
53
|
+
* Fixed a bug in the Service.start method where false positives could result.
|
54
|
+
* Updated the ServiceStatus struct to include pid and service_flags on Win2k
|
55
|
+
or later.
|
56
|
+
* Unicode is now the default setting as far as internal string handling. It
|
57
|
+
will still work fine with 'regular' text.
|
58
|
+
* Added safe string handling for string input values.
|
59
|
+
* Added rdoc comments into the C source.
|
60
|
+
* Made the service.txt and daemon.txt files rdoc friendly.
|
61
|
+
* Removed the service.rd and daemon.rd files. If you want html documentation,
|
62
|
+
run rdoc over the service.txt and daemon.txt files.
|
63
|
+
* The dreaded "code cleanup".
|
64
|
+
|
65
|
+
== 0.4.5 - 28-Feb-2005
|
66
|
+
* Fixed an accessor bug in Service#create. Thanks go to Nathaniel Talbott
|
67
|
+
for the spot.
|
68
|
+
* Eliminated a warning that appeared started in Ruby 1.8.2 regarding Struct
|
69
|
+
redefinitions.
|
70
|
+
* Moved 'examples' directory to toplevel directory.
|
71
|
+
* Deleted the 'test2.rb' example. This was supplanted by the 'daemon_test.rb'
|
72
|
+
script.
|
73
|
+
* Renamed the 'test.rb' file to 'services_test.rb'.
|
74
|
+
* Made this document rdoc friendly.
|
75
|
+
|
76
|
+
== 0.4.4 - 27-Aug-2004
|
77
|
+
* Modified the Service class to use the newer allocation framework. The
|
78
|
+
Daemon class already used this, hence no major version bump.
|
79
|
+
* Fixed in a bug in the create_service() method with regards to the
|
80
|
+
'dependencies' option and null arguments (you no longer need to specify
|
81
|
+
an empty array).
|
82
|
+
|
83
|
+
== 0.4.3 - 14-Aug-2004
|
84
|
+
* Fixed the Daemon class by adding back the constants it needed in order to
|
85
|
+
run. I accidentally broke this when I changed the Daemon class from being
|
86
|
+
a subclass of Service to being its own class.
|
87
|
+
* Added a separate test suite for the Daemon class, tc_daemon.rb, to help
|
88
|
+
me from making that mistake ever again. :)
|
89
|
+
* Updated the daemon_test.rb script a bit to report error messages should
|
90
|
+
any occur.
|
91
|
+
* Minor doc updates
|
92
|
+
|
93
|
+
== 0.4.2 - 10-Jul-2004
|
94
|
+
* The Daemon class is no longer a subclass of Service.
|
95
|
+
* Added the 'pid' and 'service_flags' struct members to the Win32Service
|
96
|
+
struct. These members are only available to folks using Windows 2000 or
|
97
|
+
later and who compile with VC++ 7.0 or later (including the .NET SDK).
|
98
|
+
* The Service.services method now accepts a group name as an optional third
|
99
|
+
argument. Again, you must be using Windows 2000 or later and compile with
|
100
|
+
VC++ 7.0 or later (including the .NET SDK).
|
101
|
+
* The deprecated STR2CSTR() functions were replaced with StringValuePtr().
|
102
|
+
This also means that as of this version, win32-service requires Ruby
|
103
|
+
1.8.0 or greater.
|
104
|
+
* Moved the sample programs to doc/examples
|
105
|
+
* Removed the .html files under /doc. You can generate that on your own if
|
106
|
+
you like.
|
107
|
+
|
108
|
+
== 0.4.1 - 14-Mar-2004
|
109
|
+
* Added the exists? class method and corresponding test suite additions.
|
110
|
+
* Pushed the ServiceError and DaemonError classes under the Win32 module.
|
111
|
+
* Normalized tc_service.rb so that it can be run outside of the test directory
|
112
|
+
more easily.
|
113
|
+
|
114
|
+
== 0.4.0 - 9-Feb-2004
|
115
|
+
* Changed "worker" method to "service_main" method.
|
116
|
+
* Added event hooks for stop, pause, resume, etc. See the documentation for
|
117
|
+
further details. (Thanks Park Heesob)
|
118
|
+
* Some of the Daemon functions were raising ServiceError. They have been
|
119
|
+
changed to DaemonError.
|
120
|
+
* Updated the daemon_test.rb file to use the new event hooks.
|
121
|
+
* Documentation additions and updates.
|
122
|
+
|
123
|
+
== 0.3.0 - 31-Jan-2004
|
124
|
+
* Added a Daemon subclass. This allows you to run Ruby programs as a service.
|
125
|
+
Please see the documentation for more details. (Thanks Park Heesob). This
|
126
|
+
should be considered an ALPHA release.
|
127
|
+
* The Win32ServiceError class has been renamed to just ServiceError. I felt
|
128
|
+
the "Win32" was redundant, given that it's already under the Win32 module.
|
129
|
+
* In some cases a bogus error description was being returned because the
|
130
|
+
GetLastError() function was being called too late. This has been fixed.
|
131
|
+
(Thanks Park Heesob).
|
132
|
+
* The explicit garbage collection has been removed because what I thought was
|
133
|
+
a memory leak was not, in fact, a memory leak. In addition, it was hurting
|
134
|
+
performance badly.
|
135
|
+
* The "\r\n" is now automatically stripped from error messages. This was
|
136
|
+
causing slightly garbled error messages. (Thanks Park Heesob).
|
137
|
+
* Added explicit closing of the Service Control Manager handle in the
|
138
|
+
services() function for those rare cases where it may fail while reading
|
139
|
+
service information.
|
140
|
+
* Made some of the error strings a bit more descriptive.
|
141
|
+
* Test suite and documentation additions, including a sample daemon program
|
142
|
+
in the test directory called "daemon_test.rb".
|
143
|
+
|
144
|
+
== 0.2.2 - 15-Jan-2004
|
145
|
+
* Fixed a mistake in the service_init declaration within Init_service().
|
146
|
+
* Fixed bug in the service_init function with regards to desired access.
|
147
|
+
* Modified service_free() function to explicitly set the hSCManager handle
|
148
|
+
to NULL and modified the service_close() method to test hSCManager handle
|
149
|
+
for NULL value. This should eliminate accidentally trying to close an
|
150
|
+
already closed handle, which may have happened as the result of a free()
|
151
|
+
call. (Thanks Park Heesob).
|
152
|
+
* Added explicit garbage collection in Service.services() method.
|
153
|
+
* More explicit about closing open HANDLE's when error conditions arise.
|
154
|
+
|
155
|
+
== 0.2.1 - 2-Nov-2003
|
156
|
+
* Made the exported less redundant and less verbose, e.g.
|
157
|
+
Service::SERVICE_DISABLED is now just Service::DISABLED. The same is true
|
158
|
+
for the service control constants, i.e. the 'SC_' has been removed.
|
159
|
+
* Corresponding test suite changes.
|
160
|
+
|
161
|
+
== 0.2.0 - 16-Oct-2003
|
162
|
+
* The constructor has been changed. It now only takes a machine name and a
|
163
|
+
desired access for arguments. The keyword arguments are now part of the
|
164
|
+
create_service method() and only in block form. See the documentation for
|
165
|
+
more details.
|
166
|
+
* Added a configure_service() and close() instance methods.
|
167
|
+
* Added several new constants to allow finer control over created and
|
168
|
+
configured services.
|
169
|
+
* Added Win32ServiceError as an exception. All failures now raise this
|
170
|
+
error instead of a vanilla StandardError.
|
171
|
+
* Moved some common code into the service.h file.
|
172
|
+
|
173
|
+
== 0.1.0 - 10-Oct-2003
|
174
|
+
- Initial release
|
data/MANIFEST
ADDED
data/README
ADDED
@@ -0,0 +1,46 @@
|
|
1
|
+
= What is it?
|
2
|
+
An interface to Win32 services. It also allows you to create an run Ruby
|
3
|
+
programs as a Service.
|
4
|
+
|
5
|
+
= Installation
|
6
|
+
== Gem Install
|
7
|
+
ruby win32-service.gemspec
|
8
|
+
gem install win32-service-X.Y.Z.gem
|
9
|
+
== Standard Install
|
10
|
+
ruby extconf.rb
|
11
|
+
nmake
|
12
|
+
cd test; ruby tc_service.rb; ruby tc_daemon.rb (optional)
|
13
|
+
nmake install
|
14
|
+
|
15
|
+
= Where are the docs?
|
16
|
+
In the 'doc' directory, or you can generate rdoc from the source files.
|
17
|
+
|
18
|
+
= Possible errors
|
19
|
+
* Service.delete causes "Unable to delete: The specified service has
|
20
|
+
been marked for deletion."
|
21
|
+
|
22
|
+
This can be caused by two things. Either you attempted to delete a running
|
23
|
+
service without stopping it first, or you have the Services administrative
|
24
|
+
tool (GUI) open. The solution is to first stop the service if it's running
|
25
|
+
and close the Services GUI admin tool before deleting.
|
26
|
+
|
27
|
+
* Service.start causes, "The service did not respond to the start or control
|
28
|
+
request in a timely fashion."
|
29
|
+
|
30
|
+
There are a few possibilities, but I'll just mention the ones I can speak of
|
31
|
+
from personal experience. The most likely cause for this error is that there
|
32
|
+
is a bug in your Daemon class. Unfortunately, it isn't stated in the
|
33
|
+
error message or the Event log as to what might be wrong. You'll have to
|
34
|
+
debug your class separately somehow. One approach might be to do
|
35
|
+
STDERR.reopen("C:\\errors.txt"), or something similar, at the top of your
|
36
|
+
Daemon code, or wrap the whole thing in a begin/rescue clause, and write the
|
37
|
+
errors to a file.
|
38
|
+
|
39
|
+
The other possibility is that your binary path name is incorrect. The
|
40
|
+
solution in the latter case is to use an absolute path name for the target
|
41
|
+
Ruby script. It might also be a good idea to include the full path name to
|
42
|
+
the Ruby interpreter, e.g. 'c:\ruby\bin\ruby' versus just 'ruby'.
|
43
|
+
|
44
|
+
= Possible test failures
|
45
|
+
The 'test_start_stop' test in the tc_service.rb file may fail. This will
|
46
|
+
happen if your W32Time service isn't running.
|
data/doc/daemon.txt
ADDED
@@ -0,0 +1,160 @@
|
|
1
|
+
= Description
|
2
|
+
The Daemon class is a wrapper class that allows you to run your code as a
|
3
|
+
Win32 service.
|
4
|
+
|
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
|
12
|
+
end
|
13
|
+
end
|
14
|
+
|
15
|
+
daemon = Daemon.new
|
16
|
+
daemon.mainloop
|
17
|
+
|
18
|
+
= Instance Methods
|
19
|
+
Daemon#mainloop
|
20
|
+
This is the method that actually puts your code into a loop and allows it
|
21
|
+
to run as a service. The code that is actually run while in the mainloop
|
22
|
+
is what you defined in the Daemon#service_main method.
|
23
|
+
|
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.
|
27
|
+
|
28
|
+
This is typically used within your service_main method. See the
|
29
|
+
tdaemon.rb file in the examples directory for an example of how it's
|
30
|
+
used in practice.
|
31
|
+
|
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.
|
37
|
+
|
38
|
+
Daemon#service_main
|
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
|
+
|
43
|
+
Daemon#state
|
44
|
+
Returns the current state of the Daemon. For a list of valid states, see
|
45
|
+
the Constants section below.
|
46
|
+
|
47
|
+
= Signal Event Hooks
|
48
|
+
These methods are called if defined within your Daemon class, and the
|
49
|
+
appropriate signal is received by your service.
|
50
|
+
|
51
|
+
Daemon#service_stop
|
52
|
+
Called if the service receives a SERVICE_CONTROL_STOP signal. This is
|
53
|
+
what the Service.stop() method sends.
|
54
|
+
|
55
|
+
Daemon#service_pause
|
56
|
+
Called if the service receives a SERVICE_CONTROL_PAUSE signal. This is
|
57
|
+
what the Service.pause() method sends.
|
58
|
+
|
59
|
+
Daemon#service_resume
|
60
|
+
Called if the service receives a SERVICE_CONTROL_CONTINUE signal. This
|
61
|
+
is what the Service.resume() method sends.
|
62
|
+
|
63
|
+
Daemon#service_interrogate
|
64
|
+
Called if the service receives a SERVICE_CONTROL_INTERROGATE signal. This
|
65
|
+
notifies a service that it should report its current status information to
|
66
|
+
the service control manager.
|
67
|
+
|
68
|
+
Daemon#service_shutdown
|
69
|
+
Called if the service receives a SERVICE_CONTROL_SHUTDOWN signal.
|
70
|
+
|
71
|
+
Daemon#service_netbindadd
|
72
|
+
Called if the service receives a SERVICE_CONTROL_NETBINDADD signal. This
|
73
|
+
notifies a network service that there is a new component for binding.
|
74
|
+
|
75
|
+
Not supported on NT 4.
|
76
|
+
|
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.
|
81
|
+
|
82
|
+
Not supported on NT 4.
|
83
|
+
|
84
|
+
Daemon#service_netbindenable
|
85
|
+
Called if the service receives a SERVICE_CONTROL_NETBINDENABLE signal.
|
86
|
+
This Notifies a network service that a disabled binding has been enabled.
|
87
|
+
|
88
|
+
Not supported on NT 4.
|
89
|
+
|
90
|
+
Daemon#service_netbindremove
|
91
|
+
Called if the service receives a SERVICE_CONTROL_NETBINDREMOVE signal.
|
92
|
+
This notifies a network service that that a component for binding has
|
93
|
+
been removed.
|
94
|
+
|
95
|
+
Not support on NT 4.
|
96
|
+
|
97
|
+
Daemon#service_paramchange
|
98
|
+
Called if the service receives a SERVICE_CONTROL_PARAMCHANGE signal.
|
99
|
+
This notifies a service that its startup parameters have changed.
|
100
|
+
|
101
|
+
= Constants
|
102
|
+
|
103
|
+
=== Service state constants
|
104
|
+
Daemon::CONTINUE_PENDING
|
105
|
+
The service continue is pending.
|
106
|
+
|
107
|
+
Daemon::PAUSE_PENDING
|
108
|
+
The service pause is pending.
|
109
|
+
|
110
|
+
Daemon::PAUSED
|
111
|
+
The service is paused (but not STOPPED).
|
112
|
+
|
113
|
+
Daemon::RUNNING
|
114
|
+
The service is running.
|
115
|
+
|
116
|
+
Daemon::START_PENDING
|
117
|
+
The service is starting (but is not yet in a RUNNING state).
|
118
|
+
|
119
|
+
Daemon::STOP_PENDING
|
120
|
+
The service is stopping (but is not yet in a STOPPED state).
|
121
|
+
|
122
|
+
Daemon::STOPPED
|
123
|
+
The service is not running.
|
124
|
+
|
125
|
+
Daemon::IDLE
|
126
|
+
The service is running, in an idle state. This is a custom state that
|
127
|
+
we added that gets around a thread blocking issue.
|
128
|
+
|
129
|
+
= Notes
|
130
|
+
You must create a service before you can actually run it. Look in the
|
131
|
+
examples directory for the files 'tdaemon.rb' and 'tdaemon_ctl.rb'. They're
|
132
|
+
small and straightforward examples of how to control, install and setup
|
133
|
+
your own Daemon.
|
134
|
+
|
135
|
+
= Known Bugs
|
136
|
+
None known. Please report any bugs you find on the Bug tracker at
|
137
|
+
http://rubyforge.org/projects/win32utils.
|
138
|
+
|
139
|
+
= Future Plans
|
140
|
+
Suggestions welcome. Please log them on the Feature Request tracker at
|
141
|
+
http://rubyforge.org/projects/win32utils
|
142
|
+
|
143
|
+
= Acknowledgements
|
144
|
+
Many thanks go to Patrick Hurley for providing the fix for the thread
|
145
|
+
blocking issue.
|
146
|
+
|
147
|
+
= Copyright
|
148
|
+
(C) 2003-2006 Daniel J. Berger, All Rights Reserved
|
149
|
+
|
150
|
+
= License
|
151
|
+
Ruby's
|
152
|
+
|
153
|
+
= Warranty
|
154
|
+
This package is provided "as is" and without any express or
|
155
|
+
implied warranties, including, without limitation, the implied
|
156
|
+
warranties of merchantability and fitness for a particular purpose.
|
157
|
+
|
158
|
+
= Author(s)
|
159
|
+
* Daniel J. Berger
|
160
|
+
* Park Heesob
|
data/doc/service.txt
ADDED
@@ -0,0 +1,382 @@
|
|
1
|
+
= Description
|
2
|
+
An interface for MS Windows Services.
|
3
|
+
|
4
|
+
= Prerequisites
|
5
|
+
Ruby 1.8.0 or later.
|
6
|
+
|
7
|
+
This package is only supported for the Windows NT family of operating
|
8
|
+
systems, e.g. NT 4, 2000, XP, 2003, etc. It is NOT supported (and won't
|
9
|
+
work) for any version of DOS or Windows 95/98/ME. It should work on Windows
|
10
|
+
XP Home, but is not officially supported for that platform.
|
11
|
+
|
12
|
+
= Synopsis
|
13
|
+
require "win32/service"
|
14
|
+
include Win32
|
15
|
+
|
16
|
+
s = Service.new("some_machine")
|
17
|
+
|
18
|
+
# Create a new service
|
19
|
+
s.create_service{ |s|
|
20
|
+
s.service_name = "foo"
|
21
|
+
s.binary_path_name = "C:\\some_dir\\foo.exe"
|
22
|
+
s.display_name = "My Foo Service"
|
23
|
+
s.service_description = "Greatest Service Ever"
|
24
|
+
}
|
25
|
+
|
26
|
+
# Configure a service that already exists
|
27
|
+
s.configure_service{ |s|
|
28
|
+
s.display_name = "My Bar Service"
|
29
|
+
}
|
30
|
+
|
31
|
+
s.close
|
32
|
+
|
33
|
+
Service.start("foo")
|
34
|
+
Service.pause("foo")
|
35
|
+
Service.resume("foo")
|
36
|
+
Service.stop("foo")
|
37
|
+
|
38
|
+
Service.delete("foo")
|
39
|
+
|
40
|
+
Service.getdisplayname("Schedule") # "Task Scheduler"
|
41
|
+
Service.getservicename("ClipBook") # "ClipSrv"
|
42
|
+
|
43
|
+
s = Service.status("ClipSrv")
|
44
|
+
|
45
|
+
# Enumerate over all services, inspecting each struct
|
46
|
+
Service.services{ |s|
|
47
|
+
p s
|
48
|
+
puts
|
49
|
+
}
|
50
|
+
|
51
|
+
= Class Methods
|
52
|
+
Service.new(host=nil, desired_access=nil){ ... }
|
53
|
+
Creates and returns a new Win32::Service handle on +host+ with the
|
54
|
+
+desired_access+. If no host is specified, your local machine is
|
55
|
+
used. If no desired access is specified, then
|
56
|
+
Service::MANAGER_CREATE_SERVICE is used.
|
57
|
+
|
58
|
+
If a block is provided the Win32::Service object is yielded to the
|
59
|
+
block and *closed* at the end of the block.
|
60
|
+
|
61
|
+
See the "Desired Access Constants" section for a list of valid
|
62
|
+
desired access levels and their meanings.
|
63
|
+
|
64
|
+
Service.delete(service, host=nil)
|
65
|
+
Deletes the specified +service+ on +host+. If no host is given,
|
66
|
+
then it deletes it on the local machine.
|
67
|
+
|
68
|
+
Service.exists?(service)
|
69
|
+
Returns true if the specified service exists, false otherwise.
|
70
|
+
|
71
|
+
Service.open(service, host=nil, desired_access=nil){ ... }
|
72
|
+
Creates and returns a new Win32::Service handle on +host+ with the
|
73
|
+
+desired_access+ for the given +service+. If no host is specified
|
74
|
+
then your local machine is used. If no +desired_access+ is specified,
|
75
|
+
then Service::SERVICE_QUERY_CONFIG is used.
|
76
|
+
|
77
|
+
If a block is provided the Win32::Service object is yielded to the
|
78
|
+
block and *closed* at the end of the block.
|
79
|
+
|
80
|
+
Note that you will probably need to change the desired access in
|
81
|
+
order to configure or delete an existing service using the returned object.
|
82
|
+
|
83
|
+
Service.pause(service, host=nil)
|
84
|
+
Pauses the specified +service+ on +host+, or the local machine if
|
85
|
+
no host is provided.
|
86
|
+
|
87
|
+
Service.resume(service, host=nil)
|
88
|
+
Resumes the specified +service+ on +host+, or the local machine if
|
89
|
+
no host is specified.
|
90
|
+
|
91
|
+
Service.services(host=nil, group=nil){ |struct| ... }
|
92
|
+
Enumerates over a list of service types on host, or the local
|
93
|
+
machine if no host is specified, yielding a Win32Service struct for each
|
94
|
+
service.
|
95
|
+
|
96
|
+
If a 'group' is specified, then only those services that belong to
|
97
|
+
that group are enumerated. If an empty string is provided, then only
|
98
|
+
services that do not belong to any group are enumerated. If this parameter
|
99
|
+
is nil, group membership is ignored and all services are enumerated.
|
100
|
+
|
101
|
+
The 'group' option is only available on Windows 2000 or later, and only
|
102
|
+
if compiled with VC++ 7.0 or later, or the .NET SDK. The Win32Service
|
103
|
+
struct contains the following members:
|
104
|
+
|
105
|
+
* service_name
|
106
|
+
* display_name
|
107
|
+
* service_type
|
108
|
+
* current_state
|
109
|
+
* controls_accepted
|
110
|
+
* win32_exit_code
|
111
|
+
* service_specific_exit_code
|
112
|
+
* check_point
|
113
|
+
* wait_hint
|
114
|
+
* binary_path_name
|
115
|
+
* start_type
|
116
|
+
* error_control
|
117
|
+
* load_order_group
|
118
|
+
* tag_id
|
119
|
+
* start_name
|
120
|
+
* dependencies
|
121
|
+
* description
|
122
|
+
* interactive?
|
123
|
+
* pid (Win2k or later)
|
124
|
+
* service_flags (Win2k or later)
|
125
|
+
|
126
|
+
Note that the 'pid' and 'service_flags' members are only available on
|
127
|
+
Windows 2000 or later, and only if built with VC++ 7.0 or later (or the
|
128
|
+
.NET SDK).
|
129
|
+
|
130
|
+
Service.start(service, host=nil, *args)
|
131
|
+
Starts the specified +service+ on +host+, or the local machine if no
|
132
|
+
host is specified. Any +args+ passed here are passed as start parameters
|
133
|
+
to the service.
|
134
|
+
|
135
|
+
Service.status(service)
|
136
|
+
Returns a Win32ServiceStatus struct for the specified service (or
|
137
|
+
raises a Win32::ServiceError if not found). The Win32ServiceStatus
|
138
|
+
struct contains the following members.
|
139
|
+
|
140
|
+
* service_type
|
141
|
+
* current_state
|
142
|
+
* controls_accepted
|
143
|
+
* win32_exit_code
|
144
|
+
* service_specific_exit_code
|
145
|
+
* check_point
|
146
|
+
* wait_hint
|
147
|
+
* interactive?
|
148
|
+
|
149
|
+
Service.stop(service, host=nil)
|
150
|
+
Stops the specified +service+ on +host+, or the local machine if no
|
151
|
+
host is specified.
|
152
|
+
|
153
|
+
= Instance Methods
|
154
|
+
Service#binary_path_name=(path_to_executable)
|
155
|
+
Sets the binary to be used for the service. The path must be the fully
|
156
|
+
qualified path name. A path that contains a space must be quoted so that
|
157
|
+
it is correctly interpreted. The path may also include arguments to the
|
158
|
+
service entry point (typically the 'main' function).
|
159
|
+
|
160
|
+
This option must be set before you can call Service#create_service.
|
161
|
+
|
162
|
+
Service#close
|
163
|
+
Closes the service handle. This is the polite way to do things, although
|
164
|
+
the service handle should automatically be closed when it goes out of
|
165
|
+
scope.
|
166
|
+
|
167
|
+
Service#configure_service{ |service| ... }
|
168
|
+
Configures the service object. Valid methods for the service object are
|
169
|
+
as follows:
|
170
|
+
|
171
|
+
* desired_access=
|
172
|
+
* service_name=
|
173
|
+
* display_name=
|
174
|
+
* service_description=
|
175
|
+
* service_type=
|
176
|
+
* start_type=
|
177
|
+
* error_control=
|
178
|
+
* tag_id=
|
179
|
+
* binary_path_name=
|
180
|
+
* load_order_group=
|
181
|
+
* start_name=
|
182
|
+
* password=
|
183
|
+
* dependencies=
|
184
|
+
* failure_action=
|
185
|
+
|
186
|
+
See the docs for individual instance methods for more details.
|
187
|
+
|
188
|
+
Service#create_service{ |service| ... }
|
189
|
+
Creates the specified service. In order for this to work, the
|
190
|
+
'service_name' and 'binary_path_name' attributes must be defined
|
191
|
+
or a Win32::ServiceError will be raised.
|
192
|
+
|
193
|
+
See the Service#configure_service method for a list of valid methods to
|
194
|
+
pass to the service object. See the individual methods for more
|
195
|
+
information, including default values.
|
196
|
+
|
197
|
+
Service#display_name=(name)
|
198
|
+
The display name to be used by user interface programs to identify the
|
199
|
+
service. The string has a maximum length of 256 characters. Case
|
200
|
+
sensitivity is preserved.
|
201
|
+
|
202
|
+
The default is to set the display name to the same string as the
|
203
|
+
service name.
|
204
|
+
|
205
|
+
Service#error_control=(type)
|
206
|
+
Sets the error control for the service. The default is
|
207
|
+
Service::ERROR_NORMAL.
|
208
|
+
|
209
|
+
See the "Error Control Contants" section for available options and their
|
210
|
+
meanings.
|
211
|
+
|
212
|
+
Service#load_order_group=(order_group)
|
213
|
+
Sets the load order group, where +order_group+ is a string that names
|
214
|
+
the load ordering group of which this service is a member. The default
|
215
|
+
is nil.
|
216
|
+
|
217
|
+
Service#machine_name=(name)
|
218
|
+
Sets the name of the machine on which the service will be created. By
|
219
|
+
default, this is set to nil. That is, it will be created on your
|
220
|
+
local machine.
|
221
|
+
|
222
|
+
Service#password=(password)
|
223
|
+
Sets the passsword to the account name specified in the Service#start_name
|
224
|
+
method. By default, this value is set to nil, which is appropriate if
|
225
|
+
the account has no password or if the service runs in the
|
226
|
+
'LocalService', 'NetworkService', or 'LocalSystem' account.
|
227
|
+
|
228
|
+
Note that passwords are ignored for driver services.
|
229
|
+
|
230
|
+
Service#service_name=(name)
|
231
|
+
Sets the service name for the service. This value must be set in order
|
232
|
+
to create a service. The string has a maximum length of 256 characters.
|
233
|
+
|
234
|
+
Service#service_type=(type)
|
235
|
+
Sets the service type for the service. The default is
|
236
|
+
Service::WIN32_OWN_PROCESS | Service::INTERACTIVE_PROCESS.
|
237
|
+
|
238
|
+
See the "Service Type Contants" section for available options and their
|
239
|
+
meanings.
|
240
|
+
|
241
|
+
Service#start_name=(name)
|
242
|
+
Sets the name of the account under which the service should run.
|
243
|
+
By default the 'LocalSystem' account is used.
|
244
|
+
|
245
|
+
Service#start_type=(type)
|
246
|
+
Sets the start type for the service. The default is Service::DEMAND_START.
|
247
|
+
|
248
|
+
See the "Start Type Contants" section for available options and their
|
249
|
+
meanings.
|
250
|
+
|
251
|
+
= Constants
|
252
|
+
|
253
|
+
=== Standard Constants
|
254
|
+
VERSION
|
255
|
+
The current version number of this package, returned as a string.
|
256
|
+
|
257
|
+
=== Desired Access Constants
|
258
|
+
Service::MANAGER_ALL_ACCESS
|
259
|
+
Includes STANDARD_RIGHTS_REQUIRED, in addition to all access rights
|
260
|
+
in the table.
|
261
|
+
|
262
|
+
Service::MANAGER_CREATE_SERVICE
|
263
|
+
Required to call the CreateService function to create a service object
|
264
|
+
and add it to the database.
|
265
|
+
|
266
|
+
Service::MANAGER_CONNECT
|
267
|
+
Required to connect to the service control manager.
|
268
|
+
|
269
|
+
Service::MANAGER_ENUMERATE_SERVICE
|
270
|
+
Required to call the EnumServicesStatus function to list the services
|
271
|
+
that are in the database.
|
272
|
+
|
273
|
+
Service::MANAGER_LOCK
|
274
|
+
Required to call the LockServiceDatabase function to acquire a lock on the
|
275
|
+
database.
|
276
|
+
|
277
|
+
Service::MANAGER_BOOT_CONFIG
|
278
|
+
Required to call the NotifyBootConfigStatus() (internal) function. Not
|
279
|
+
defined with all compilers.
|
280
|
+
|
281
|
+
Service::MANAGER_QUERY_LOCK_STATUS
|
282
|
+
Required to call the QueryServiceLockStatus() (internal) function to
|
283
|
+
retrieve the lock status information for the database.
|
284
|
+
|
285
|
+
=== Service Type Constants
|
286
|
+
Service::FILE_SYSTEM_DRIVER
|
287
|
+
File system driver service.
|
288
|
+
|
289
|
+
Service::KERNEL_DRIVER
|
290
|
+
Driver service.
|
291
|
+
|
292
|
+
Service::WIN32_OWN_PROCESS
|
293
|
+
Service that runs in its own process.
|
294
|
+
|
295
|
+
Service::WIN32_SHARE_PROCESS
|
296
|
+
Service that shares a process with one or more other services.
|
297
|
+
|
298
|
+
Service::INTERACTIVE_PROCESS
|
299
|
+
The service can interact with the desktop. This can only be used if
|
300
|
+
either SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS is
|
301
|
+
specified as well, and the service is running in the context of the
|
302
|
+
LocalSystem account (which is the default for this module, btw).
|
303
|
+
|
304
|
+
=== Start Type Constants
|
305
|
+
Service::AUTO_START
|
306
|
+
A service started automatically by the service control manager during
|
307
|
+
system startup.
|
308
|
+
|
309
|
+
Service::BOOT_START
|
310
|
+
A device driver started by the system loader. This value is valid only
|
311
|
+
for driver services.
|
312
|
+
|
313
|
+
Service::DEMAND_START
|
314
|
+
A service started by the service control manager when a process calls
|
315
|
+
the StartService() function.
|
316
|
+
|
317
|
+
Service::DISABLED
|
318
|
+
A service that cannot be started. Attempts to start the service result
|
319
|
+
in an error.
|
320
|
+
|
321
|
+
Service::SYSTEM_START
|
322
|
+
A device driver started by the IoInitSystem() function. This value is
|
323
|
+
valid only for driver services.
|
324
|
+
|
325
|
+
=== Error Control Constants
|
326
|
+
Service::ERROR_IGNORE
|
327
|
+
The startup program logs the error but continues the startup operation.
|
328
|
+
|
329
|
+
Service::ERROR_NORMAL
|
330
|
+
The startup program logs the error and puts up a message box pop-up but
|
331
|
+
continues the startup operation.
|
332
|
+
|
333
|
+
Service::ERROR_SEVERE
|
334
|
+
The startup program logs the error. If the last-known-good configuration
|
335
|
+
is being started, the startup operation continues. Otherwise, the system
|
336
|
+
is restarted with the last-known-good configuration.
|
337
|
+
|
338
|
+
Service::ERROR_CRITICAL
|
339
|
+
The startup program logs the error, if possible. If the last-known-good
|
340
|
+
configuration is being started the startup operation fails. Otherwise,
|
341
|
+
the system is restarted with the last-known-good configuration.
|
342
|
+
|
343
|
+
= Notes
|
344
|
+
See the MSDN API with regards to CreateService(), etc at
|
345
|
+
http://www.msdn.com
|
346
|
+
|
347
|
+
Some API ideas taken (or not) from both Python's win32serviceutil.py and
|
348
|
+
Perl's Win32::Service module.
|
349
|
+
|
350
|
+
I don't truly understand how to allow a tag_id in the create_service()
|
351
|
+
method, so for now it's set to NULL automatically. Suggestions welcome.
|
352
|
+
|
353
|
+
= Known Bugs
|
354
|
+
There may be a failure in the test suite if the W32Time dependency is
|
355
|
+
not started.
|
356
|
+
|
357
|
+
If you find any bugs please log them on the bug tracker. You can find it
|
358
|
+
on the project page at http://www.rubyforge.org/projects/win32utils.
|
359
|
+
|
360
|
+
= Acknowledgements
|
361
|
+
Many thanks go to Patrick Hurley for providing the fix for the thread
|
362
|
+
blocking issue.
|
363
|
+
|
364
|
+
= Future Plans
|
365
|
+
Add Tag_ID support.
|
366
|
+
Add ability to create or modify service failure actions.
|
367
|
+
Use RegisterServiceCtrlHandlerEx().
|
368
|
+
|
369
|
+
= Copyright
|
370
|
+
(C) 2003-2006, Daniel J. Berger, All Rights Reserved
|
371
|
+
|
372
|
+
= License
|
373
|
+
Ruby's
|
374
|
+
|
375
|
+
= Warranty
|
376
|
+
This package is provided "as is" and without any express or
|
377
|
+
implied warranties, including, without limitation, the implied
|
378
|
+
warranties of merchantability and fitness for a particular purpose.
|
379
|
+
|
380
|
+
== Author(s)
|
381
|
+
* Daniel J. Berger
|
382
|
+
* Park Heesob
|