win32-service 0.5.2 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/CHANGES +37 -1
- data/MANIFEST +18 -16
- data/README +26 -28
- data/doc/daemon.txt +54 -55
- data/doc/service.txt +123 -134
- data/ext/extconf.rb +5 -0
- data/ext/win32/daemon.c +592 -0
- data/lib/win32/service.rb +1539 -0
- data/test/tc_daemon.rb +14 -18
- data/test/tc_service.rb +221 -367
- data/test/tc_service_create.rb +83 -0
- data/test/tc_service_info.rb +170 -0
- data/test/tc_service_status.rb +108 -0
- metadata +63 -40
- data/extconf.rb +0 -18
- data/lib/win32/service.c +0 -2131
- data/lib/win32/service.h +0 -416
data/CHANGES
CHANGED
@@ -1,3 +1,39 @@
|
|
1
|
+
== 0.6.0 - 25-Nov-2007
|
2
|
+
* The Service control class is now pure Ruby. The Daemon class is still C,
|
3
|
+
however. That may change in the future. This means the windows-pr
|
4
|
+
library is now a prerequisite.
|
5
|
+
* The Service.new method has been altered in a way that is not backwards
|
6
|
+
compatible. It is now the same as Service.create.
|
7
|
+
* The Service.start method now properly handles arguments to the
|
8
|
+
Daemon#service_main method.
|
9
|
+
* The Daemon source code is now separate from the Service control class
|
10
|
+
source code. That means you must require them separately, as needed.
|
11
|
+
* The Daemon class should be much more responsive to service events now,
|
12
|
+
especially service_stop. Many thanks go to Kevin Burge for the patch.
|
13
|
+
* Added the Daemon.mainloop method as a shortcut for Daemon.new.mainloop.
|
14
|
+
* The Daemon class now redirects STDIN, STDOUT and STDERR to the NUL device
|
15
|
+
if they're still associated with a terminal when the service starts. This
|
16
|
+
should help prevent Errno::EBADF errors.
|
17
|
+
* The Service.services class method now supports the group parameter for
|
18
|
+
versions of Ruby built with older compilers, i.e. it will now work with
|
19
|
+
the one-click Ruby installer.
|
20
|
+
* The Service.getdisplayname method was changed to Service.get_display_name.
|
21
|
+
An alias has been provided for backwards compatibility.
|
22
|
+
* The Service.getservicename method was changed to Service.get_service_name.
|
23
|
+
An alias has been provided for backwards compatibility.
|
24
|
+
* Added the Service.config_info method.
|
25
|
+
* The Service.create and Service.configure methods now allow you to set
|
26
|
+
failure actions, failure commands, and reset/retry periods.
|
27
|
+
* Improved test suite.
|
28
|
+
* Changed 'tdaemon.rb', 'tdaemon_ctl.rb' and 'service_test.rb' to
|
29
|
+
'demo_daemon.rb', 'demo_daemon_ctl.rb' and 'demo_services.rb', respectively.
|
30
|
+
* Some refactoring and updates to the demo daemon and demo daemon controller
|
31
|
+
examples.
|
32
|
+
* The Win32Service struct is now ServiceInfo.
|
33
|
+
* ServiceError is now Service::Error.
|
34
|
+
* DaemonError is now Daemon::Error.
|
35
|
+
* Some documentation improvements, corrections and updates.
|
36
|
+
|
1
37
|
== 0.5.2 - 25-Nov-2006
|
2
38
|
* Fixed a bug in the Daemon class where the service event handling methods
|
3
39
|
(most notably service_stop) did not work properly due to thread blocking
|
@@ -65,7 +101,7 @@
|
|
65
101
|
== 0.4.5 - 28-Feb-2005
|
66
102
|
* Fixed an accessor bug in Service#create. Thanks go to Nathaniel Talbott
|
67
103
|
for the spot.
|
68
|
-
* Eliminated a warning that appeared
|
104
|
+
* Eliminated a warning that appeared starting in Ruby 1.8.2 regarding Struct
|
69
105
|
redefinitions.
|
70
106
|
* Moved 'examples' directory to toplevel directory.
|
71
107
|
* Deleted the 'test2.rb' example. This was supplanted by the 'daemon_test.rb'
|
data/MANIFEST
CHANGED
@@ -1,16 +1,18 @@
|
|
1
|
-
MANIFEST
|
2
|
-
CHANGES
|
3
|
-
README
|
4
|
-
|
5
|
-
|
6
|
-
doc/daemon.txt
|
7
|
-
doc/service.txt
|
8
|
-
|
9
|
-
|
10
|
-
examples/
|
11
|
-
|
12
|
-
|
13
|
-
lib/win32/service.
|
14
|
-
|
15
|
-
test/
|
16
|
-
test/
|
1
|
+
* MANIFEST
|
2
|
+
* CHANGES
|
3
|
+
* README
|
4
|
+
* Rakefile
|
5
|
+
* win32-service.gemspec
|
6
|
+
* doc/daemon.txt
|
7
|
+
* doc/service.txt
|
8
|
+
* ext/extconf.rb
|
9
|
+
* ext/win32/daemonc.c
|
10
|
+
* examples/demo_daemon.rb
|
11
|
+
* examples/demo_daemon_ctl.rb
|
12
|
+
* examples/demo_services.rb
|
13
|
+
* lib/win32/service.rb
|
14
|
+
* test/tc_daemon.rb
|
15
|
+
* test/tc_service_create.rb
|
16
|
+
* test/tc_service_info.rb
|
17
|
+
* test/tc_service_status.rb
|
18
|
+
* test/tc_service.rb
|
data/README
CHANGED
@@ -1,19 +1,13 @@
|
|
1
|
-
=
|
2
|
-
|
3
|
-
programs as a Service.
|
1
|
+
= Description
|
2
|
+
The win32-service library allows you to control or create MS Windows services.
|
4
3
|
|
5
4
|
= Installation
|
6
|
-
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
|
11
|
-
|
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.
|
5
|
+
rake test (optional)
|
6
|
+
rake install
|
7
|
+
|
8
|
+
= Documentation
|
9
|
+
Please see the documentation in the 'doc' directory, or the gem documentation
|
10
|
+
that was installed when you installed this library as a gem.
|
17
11
|
|
18
12
|
= Possible errors
|
19
13
|
* Service.delete causes "Unable to delete: The specified service has
|
@@ -27,20 +21,24 @@ and close the Services GUI admin tool before deleting.
|
|
27
21
|
* Service.start causes, "The service did not respond to the start or control
|
28
22
|
request in a timely fashion."
|
29
23
|
|
30
|
-
|
31
|
-
|
32
|
-
|
33
|
-
|
34
|
-
|
35
|
-
|
36
|
-
|
37
|
-
errors to a file.
|
24
|
+
The best way to debug your services is to wrap your entire Daemon subclass
|
25
|
+
in a begin/end block and send error messages to a file. That should give a
|
26
|
+
good clue as to the nature of the problem. The most probable culprits are:
|
27
|
+
|
28
|
+
* You've tried to require a library that's not in your $LOAD_PATH. Make sure
|
29
|
+
that your require statements are inside the begin/rescue block so that you can
|
30
|
+
easily find those mistakes.
|
38
31
|
|
39
|
-
|
40
|
-
|
41
|
-
|
42
|
-
|
32
|
+
* Your have a bad binary path name. Be sure to use an absolute path name for
|
33
|
+
the binary path name, including the full path to the Ruby interpreter, e.g.
|
34
|
+
'c:\ruby\bin\ruby' instead of just 'ruby'.
|
35
|
+
|
36
|
+
* You've got a syntax error in your code somewhere.
|
43
37
|
|
44
38
|
= Possible test failures
|
45
|
-
The '
|
46
|
-
happen if your W32Time service isn't running.
|
39
|
+
The 'test_service_start_stop' test in the tc_service.rb file may fail. This
|
40
|
+
will happen if your W32Time service isn't running.
|
41
|
+
|
42
|
+
= Future Plans
|
43
|
+
* Pure Ruby Daemon class
|
44
|
+
* Add service_session_change hook
|
data/doc/daemon.txt
CHANGED
@@ -1,8 +1,8 @@
|
|
1
|
-
|
1
|
+
= Description
|
2
2
|
The Daemon class is a wrapper class that allows you to run your code as a
|
3
|
-
|
3
|
+
Windows service.
|
4
4
|
|
5
|
-
|
5
|
+
= Synopsis
|
6
6
|
class Daemon
|
7
7
|
def service_main
|
8
8
|
while running?
|
@@ -12,56 +12,58 @@
|
|
12
12
|
end
|
13
13
|
end
|
14
14
|
|
15
|
-
|
16
|
-
daemon.mainloop
|
15
|
+
Daemon.mainloop
|
17
16
|
|
18
|
-
|
19
|
-
Daemon
|
17
|
+
= Class Methods
|
18
|
+
Daemon.mainloop
|
20
19
|
This is the method that actually puts your code into a loop and allows it
|
21
|
-
to run as a service.
|
20
|
+
to run as a service. The code that is actually run while in the mainloop
|
22
21
|
is what you defined in the Daemon#service_main method.
|
23
|
-
|
22
|
+
|
23
|
+
= Instance Methods
|
24
24
|
Daemon#running?
|
25
|
-
Returns whether or not the daemon is running.
|
25
|
+
Returns whether or not the daemon is running. This is just a shortcut
|
26
26
|
for checking if the state is RUNNING, PAUSED or IDLE.
|
27
27
|
|
28
|
-
This is typically used within your service_main method.
|
29
|
-
|
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
30
|
used in practice.
|
31
31
|
|
32
32
|
Daemon#service_init
|
33
33
|
Any code defined defined within this method occurs before service_main is
|
34
|
-
reached.
|
35
|
-
execute should be placed here.
|
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
36
|
you try to start it.
|
37
37
|
|
38
|
-
Daemon#service_main
|
38
|
+
Daemon#service_main(*args)
|
39
39
|
You are expected to define your own service_main() method. The code
|
40
40
|
defined in this method is the code that will run while running as a
|
41
41
|
service.
|
42
|
+
|
43
|
+
Any +args+ passed to Service.start are passed to this method.
|
42
44
|
|
43
45
|
Daemon#state
|
44
|
-
Returns the current state of the Daemon.
|
46
|
+
Returns the current state of the Daemon. For a list of valid states, see
|
45
47
|
the Constants section below.
|
46
48
|
|
47
|
-
|
49
|
+
= Signal Event Hooks
|
48
50
|
These methods are called if defined within your Daemon class, and the
|
49
51
|
appropriate signal is received by your service.
|
50
52
|
|
51
53
|
Daemon#service_stop
|
52
|
-
Called if the service receives a SERVICE_CONTROL_STOP signal.
|
54
|
+
Called if the service receives a SERVICE_CONTROL_STOP signal. This is
|
53
55
|
what the Service.stop() method sends.
|
54
56
|
|
55
57
|
Daemon#service_pause
|
56
|
-
Called if the service receives a SERVICE_CONTROL_PAUSE signal.
|
58
|
+
Called if the service receives a SERVICE_CONTROL_PAUSE signal. This is
|
57
59
|
what the Service.pause() method sends.
|
58
60
|
|
59
61
|
Daemon#service_resume
|
60
|
-
Called if the service receives a SERVICE_CONTROL_CONTINUE signal.
|
62
|
+
Called if the service receives a SERVICE_CONTROL_CONTINUE signal. This
|
61
63
|
is what the Service.resume() method sends.
|
62
64
|
|
63
65
|
Daemon#service_interrogate
|
64
|
-
Called if the service receives a SERVICE_CONTROL_INTERROGATE signal.
|
66
|
+
Called if the service receives a SERVICE_CONTROL_INTERROGATE signal. This
|
65
67
|
notifies a service that it should report its current status information to
|
66
68
|
the service control manager.
|
67
69
|
|
@@ -69,88 +71,85 @@ Daemon#service_shutdown
|
|
69
71
|
Called if the service receives a SERVICE_CONTROL_SHUTDOWN signal.
|
70
72
|
|
71
73
|
Daemon#service_netbindadd
|
72
|
-
Called if the service receives a SERVICE_CONTROL_NETBINDADD signal.
|
74
|
+
Called if the service receives a SERVICE_CONTROL_NETBINDADD signal. This
|
73
75
|
notifies a network service that there is a new component for binding.
|
74
76
|
|
75
|
-
Not supported on NT 4.
|
76
|
-
|
77
77
|
Daemon#service_netbinddisable
|
78
78
|
Called if the service receives a SERVICE_CONTROL_NETBINDDISABLE signal.
|
79
79
|
This notifies a network service that one of its bindings has been
|
80
80
|
disabled.
|
81
81
|
|
82
|
-
Not supported on NT 4.
|
83
|
-
|
84
82
|
Daemon#service_netbindenable
|
85
83
|
Called if the service receives a SERVICE_CONTROL_NETBINDENABLE signal.
|
86
84
|
This Notifies a network service that a disabled binding has been enabled.
|
87
85
|
|
88
|
-
Not supported on NT 4.
|
89
|
-
|
90
86
|
Daemon#service_netbindremove
|
91
87
|
Called if the service receives a SERVICE_CONTROL_NETBINDREMOVE signal.
|
92
88
|
This notifies a network service that that a component for binding has
|
93
89
|
been removed.
|
94
90
|
|
95
|
-
Not support on NT 4.
|
96
|
-
|
97
91
|
Daemon#service_paramchange
|
98
92
|
Called if the service receives a SERVICE_CONTROL_PARAMCHANGE signal.
|
99
93
|
This notifies a service that its startup parameters have changed.
|
100
94
|
|
101
|
-
|
95
|
+
= Constants
|
102
96
|
|
103
97
|
=== Service state constants
|
104
|
-
CONTINUE_PENDING
|
98
|
+
Daemon::CONTINUE_PENDING
|
105
99
|
The service continue is pending.
|
106
100
|
|
107
|
-
PAUSE_PENDING
|
101
|
+
Daemon::PAUSE_PENDING
|
108
102
|
The service pause is pending.
|
109
103
|
|
110
|
-
PAUSED
|
104
|
+
Daemon::PAUSED
|
111
105
|
The service is paused (but not STOPPED).
|
112
106
|
|
113
|
-
RUNNING
|
107
|
+
Daemon::RUNNING
|
114
108
|
The service is running.
|
115
109
|
|
116
|
-
START_PENDING
|
110
|
+
Daemon::START_PENDING
|
117
111
|
The service is starting (but is not yet in a RUNNING state).
|
118
112
|
|
119
|
-
STOP_PENDING
|
113
|
+
Daemon::STOP_PENDING
|
120
114
|
The service is stopping (but is not yet in a STOPPED state).
|
121
115
|
|
122
|
-
STOPPED
|
116
|
+
Daemon::STOPPED
|
123
117
|
The service is not running.
|
124
118
|
|
125
|
-
IDLE
|
126
|
-
The service is running, in an idle state.
|
119
|
+
Daemon::IDLE
|
120
|
+
The service is running, in an idle state. This is a custom state that
|
127
121
|
we added that gets around a thread blocking issue.
|
128
122
|
|
129
|
-
|
130
|
-
You must create a service before you can actually run it.
|
131
|
-
examples directory for the files '
|
132
|
-
small and straightforward examples of how to control, install and
|
133
|
-
your own Daemon.
|
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.
|
134
128
|
|
135
|
-
|
129
|
+
= Known Bugs
|
136
130
|
None known. Please report any bugs you find on the Bug tracker at
|
137
131
|
http://rubyforge.org/projects/win32utils.
|
138
132
|
|
139
|
-
|
140
|
-
Suggestions welcome.
|
133
|
+
= Future Plans
|
134
|
+
Suggestions welcome. Please log them on the Feature Request tracker at
|
141
135
|
http://rubyforge.org/projects/win32utils
|
136
|
+
|
137
|
+
= Acknowledgements
|
138
|
+
Many thanks go to Patrick Hurley for providing the fix for the thread
|
139
|
+
blocking issue. Thanks also go to Kevin Burge for his patch that solved
|
140
|
+
service responsiveness issues.
|
142
141
|
|
143
|
-
|
144
|
-
(C) 2003-
|
142
|
+
= Copyright
|
143
|
+
(C) 2003-2007 Daniel J. Berger, All Rights Reserved
|
145
144
|
|
146
|
-
|
145
|
+
= License
|
147
146
|
Ruby's
|
148
147
|
|
149
|
-
|
148
|
+
= Warranty
|
150
149
|
This package is provided "as is" and without any express or
|
151
150
|
implied warranties, including, without limitation, the implied
|
152
151
|
warranties of merchantability and fitness for a particular purpose.
|
153
152
|
|
154
|
-
|
155
|
-
|
156
|
-
|
153
|
+
= Author(s)
|
154
|
+
* Daniel J. Berger
|
155
|
+
* Park Heesob
|
data/doc/service.txt
CHANGED
@@ -1,34 +1,39 @@
|
|
1
|
-
|
2
|
-
An interface for
|
1
|
+
= Description
|
2
|
+
An interface for MS Windows Services.
|
3
3
|
|
4
|
-
|
4
|
+
= Prerequisites
|
5
5
|
Ruby 1.8.0 or later.
|
6
6
|
|
7
7
|
This package is only supported for the Windows NT family of operating
|
8
|
-
systems, e.g.
|
9
|
-
work) for any version of DOS or Windows 95/98/ME. It
|
10
|
-
|
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
|
+
|
12
|
+
It should work on Windows XP Home, but is not officially supported for
|
13
|
+
that platform.
|
11
14
|
|
12
|
-
|
15
|
+
= Synopsis
|
13
16
|
require "win32/service"
|
14
17
|
include Win32
|
15
18
|
|
16
19
|
s = Service.new("some_machine")
|
17
20
|
|
18
21
|
# Create a new service
|
19
|
-
|
20
|
-
|
21
|
-
|
22
|
-
|
23
|
-
|
24
|
-
|
22
|
+
Service.create('some_service', nil,
|
23
|
+
:service_type => Service::WIN32_OWN_PROCESS,
|
24
|
+
:description => 'A custom service I wrote just for fun'
|
25
|
+
:start_type => Service::AUTO_START,
|
26
|
+
:error_control => Service::ERROR_NORMAL,
|
27
|
+
:binary_path_name => 'C:\path\to\some_service.exe',
|
28
|
+
:load_order_group => 'Network',
|
29
|
+
:dependencies => ['W32Time','Schedule']
|
30
|
+
:service_start_name => 'SomeDomain\\User',
|
31
|
+
:password => 'XXXXXXX',
|
32
|
+
:display_name => 'This is some service',
|
33
|
+
)
|
25
34
|
|
26
35
|
# Configure a service that already exists
|
27
|
-
|
28
|
-
s.display_name = "My Bar Service"
|
29
|
-
}
|
30
|
-
|
31
|
-
s.close
|
36
|
+
Service.configure(:display_name => "My Bar Service")
|
32
37
|
|
33
38
|
Service.start("foo")
|
34
39
|
Service.pause("foo")
|
@@ -37,10 +42,10 @@
|
|
37
42
|
|
38
43
|
Service.delete("foo")
|
39
44
|
|
40
|
-
Service.
|
41
|
-
Service.
|
42
|
-
|
43
|
-
|
45
|
+
Service.get_display_name("Schedule") # "Task Scheduler"
|
46
|
+
Service.get_service_name("ClipBook") # "ClipSrv"
|
47
|
+
|
48
|
+
Service.status('W32Time') => <struct Struct::ServiceStatus ...>
|
44
49
|
|
45
50
|
# Enumerate over all services, inspecting each struct
|
46
51
|
Service.services{ |s|
|
@@ -48,18 +53,46 @@
|
|
48
53
|
puts
|
49
54
|
}
|
50
55
|
|
51
|
-
|
52
|
-
Service.new(host=nil,
|
53
|
-
Creates
|
54
|
-
|
55
|
-
|
56
|
-
Service::MANAGER_CREATE_SERVICE is used.
|
56
|
+
= Class Methods
|
57
|
+
Service.new(service_name, host=nil, options={})
|
58
|
+
Creates a new service with +service_name+ on +host+, or the local host
|
59
|
+
if no host is specified. The +options+ parameter is a hash that can
|
60
|
+
contain any of the following parameters, and their default values:
|
57
61
|
|
58
|
-
|
59
|
-
|
60
|
-
|
61
|
-
|
62
|
-
|
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
|
+
|
74
|
+
Service.configure(service_name, host=nil, options={})
|
75
|
+
Configures the named +service_name+ on +host+, or the local host if no
|
76
|
+
host is specified. The +options+ parameter is a hash that can contain any
|
77
|
+
of the following parameters:
|
78
|
+
|
79
|
+
* service_type
|
80
|
+
* start_type
|
81
|
+
* error_control
|
82
|
+
* binary_path_name
|
83
|
+
* load_order_group
|
84
|
+
* dependencies
|
85
|
+
* service_start_name
|
86
|
+
* password (used with service_start_name)
|
87
|
+
* display_name
|
88
|
+
* description
|
89
|
+
|
90
|
+
Service.config_info(service, host=nil)
|
91
|
+
Returns a ServiceConfigInfo struct containing the configuration information
|
92
|
+
about +service+ on +host+, or the local host if no host is specified.
|
93
|
+
|
94
|
+
Service.create
|
95
|
+
Alias for Service.new
|
63
96
|
|
64
97
|
Service.delete(service, host=nil)
|
65
98
|
Deletes the specified +service+ on +host+. If no host is given,
|
@@ -67,18 +100,6 @@ Service.delete(service, host=nil)
|
|
67
100
|
|
68
101
|
Service.exists?(service)
|
69
102
|
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
103
|
|
83
104
|
Service.pause(service, host=nil)
|
84
105
|
Pauses the specified +service+ on +host+, or the local machine if
|
@@ -134,7 +155,7 @@ Service.start(service, host=nil, *args)
|
|
134
155
|
|
135
156
|
Service.status(service)
|
136
157
|
Returns a Win32ServiceStatus struct for the specified service (or
|
137
|
-
raises a
|
158
|
+
raises a Win32::ServiceError if not found). The Win32ServiceStatus
|
138
159
|
struct contains the following members.
|
139
160
|
|
140
161
|
* service_type
|
@@ -150,105 +171,68 @@ Service.stop(service, host=nil)
|
|
150
171
|
Stops the specified +service+ on +host+, or the local machine if no
|
151
172
|
host is specified.
|
152
173
|
|
153
|
-
|
154
|
-
|
155
|
-
|
156
|
-
|
157
|
-
|
158
|
-
|
159
|
-
|
160
|
-
|
161
|
-
|
162
|
-
|
163
|
-
|
164
|
-
|
165
|
-
|
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 Win32ServiceError 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.
|
174
|
+
= Create and configure options
|
175
|
+
binary_path_name
|
176
|
+
The binary to be used for the service. The path must be the fully
|
177
|
+
qualified path name. A path that contains a space must be quoted so that
|
178
|
+
it is correctly interpreted. The path may also include arguments to the
|
179
|
+
service entry point (typically the 'main' function).
|
180
|
+
|
181
|
+
dependencies
|
182
|
+
Any dependencies the service has in order to run. This can be a string
|
183
|
+
or an array of strings.
|
184
|
+
|
185
|
+
description
|
186
|
+
A text string describing the service.
|
196
187
|
|
197
|
-
|
188
|
+
display_name
|
198
189
|
The display name to be used by user interface programs to identify the
|
199
|
-
service.
|
190
|
+
service. The string has a maximum length of 256 characters. Case
|
200
191
|
sensitivity is preserved.
|
201
192
|
|
202
193
|
The default is to set the display name to the same string as the
|
203
194
|
service name.
|
204
195
|
|
205
|
-
|
206
|
-
|
207
|
-
Service::ERROR_NORMAL.
|
196
|
+
error_control
|
197
|
+
The error control for the service. The default is Service::ERROR_NORMAL.
|
208
198
|
|
209
199
|
See the "Error Control Contants" section for available options and their
|
210
200
|
meanings.
|
211
201
|
|
212
|
-
|
213
|
-
|
214
|
-
|
215
|
-
is nil.
|
216
|
-
|
217
|
-
Service#machine_name=(name=nil)
|
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.
|
202
|
+
load_order_group
|
203
|
+
The load order group, a string that names the load ordering group of
|
204
|
+
which this service is a member. The default is nil.
|
221
205
|
|
222
|
-
|
223
|
-
Sets the passsword to the account name specified in the
|
206
|
+
password
|
207
|
+
Sets the passsword to the account name specified in the Service#start_name
|
224
208
|
method. By default, this value is set to nil, which is appropriate if
|
225
209
|
the account has no password or if the service runs in the
|
226
210
|
'LocalService', 'NetworkService', or 'LocalSystem' account.
|
227
211
|
|
228
212
|
Note that passwords are ignored for driver services.
|
229
213
|
|
230
|
-
|
231
|
-
|
232
|
-
to create a service.
|
214
|
+
service_name
|
215
|
+
The service name for the service. This value must be set in order
|
216
|
+
to create a service. The string has a maximum length of 256 characters.
|
233
217
|
|
234
|
-
|
235
|
-
|
218
|
+
service_type
|
219
|
+
The service type for the service. The default is
|
236
220
|
Service::WIN32_OWN_PROCESS | Service::INTERACTIVE_PROCESS.
|
237
221
|
|
238
222
|
See the "Service Type Contants" section for available options and their
|
239
223
|
meanings.
|
240
224
|
|
241
|
-
|
225
|
+
start_name
|
242
226
|
Sets the name of the account under which the service should run.
|
243
|
-
|
227
|
+
By default the 'LocalSystem' account is used.
|
244
228
|
|
245
|
-
|
246
|
-
|
229
|
+
start_type
|
230
|
+
The start type for the service. The default is Service::DEMAND_START.
|
247
231
|
|
248
232
|
See the "Start Type Contants" section for available options and their
|
249
233
|
meanings.
|
250
234
|
|
251
|
-
|
235
|
+
= Constants
|
252
236
|
|
253
237
|
=== Standard Constants
|
254
238
|
VERSION
|
@@ -275,14 +259,14 @@ Service::MANAGER_LOCK
|
|
275
259
|
database.
|
276
260
|
|
277
261
|
Service::MANAGER_BOOT_CONFIG
|
278
|
-
Required to call the NotifyBootConfigStatus function. Not
|
279
|
-
all compilers.
|
262
|
+
Required to call the NotifyBootConfigStatus() (internal) function. Not
|
263
|
+
defined with all compilers.
|
280
264
|
|
281
265
|
Service::MANAGER_QUERY_LOCK_STATUS
|
282
|
-
Required to call the QueryServiceLockStatus function to
|
283
|
-
lock status information for the database.
|
266
|
+
Required to call the QueryServiceLockStatus() (internal) function to
|
267
|
+
retrieve the lock status information for the database.
|
284
268
|
|
285
|
-
|
269
|
+
=== Service Type Constants
|
286
270
|
Service::FILE_SYSTEM_DRIVER
|
287
271
|
File system driver service.
|
288
272
|
|
@@ -301,7 +285,7 @@ Service::INTERACTIVE_PROCESS
|
|
301
285
|
specified as well, and the service is running in the context of the
|
302
286
|
LocalSystem account (which is the default for this module, btw).
|
303
287
|
|
304
|
-
|
288
|
+
=== Start Type Constants
|
305
289
|
Service::AUTO_START
|
306
290
|
A service started automatically by the service control manager during
|
307
291
|
system startup.
|
@@ -322,7 +306,7 @@ Service::SYSTEM_START
|
|
322
306
|
A device driver started by the IoInitSystem() function. This value is
|
323
307
|
valid only for driver services.
|
324
308
|
|
325
|
-
|
309
|
+
=== Error Control Constants
|
326
310
|
Service::ERROR_IGNORE
|
327
311
|
The startup program logs the error but continues the startup operation.
|
328
312
|
|
@@ -340,7 +324,7 @@ Service::ERROR_CRITICAL
|
|
340
324
|
configuration is being started the startup operation fails. Otherwise,
|
341
325
|
the system is restarted with the last-known-good configuration.
|
342
326
|
|
343
|
-
|
327
|
+
= Notes
|
344
328
|
See the MSDN API with regards to CreateService(), etc at
|
345
329
|
http://www.msdn.com
|
346
330
|
|
@@ -350,29 +334,34 @@ Service::ERROR_CRITICAL
|
|
350
334
|
I don't truly understand how to allow a tag_id in the create_service()
|
351
335
|
method, so for now it's set to NULL automatically. Suggestions welcome.
|
352
336
|
|
353
|
-
|
337
|
+
= Known Bugs
|
354
338
|
There may be a failure in the test suite if the W32Time dependency is
|
355
339
|
not started.
|
356
340
|
|
357
|
-
|
358
|
-
|
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.
|
343
|
+
|
344
|
+
= Acknowledgements
|
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.
|
359
348
|
|
360
|
-
|
349
|
+
= Future Plans
|
361
350
|
Add Tag_ID support.
|
362
351
|
Add ability to create or modify service failure actions.
|
363
352
|
Use RegisterServiceCtrlHandlerEx().
|
364
353
|
|
365
|
-
|
366
|
-
(C) 2003-
|
354
|
+
= Copyright
|
355
|
+
(C) 2003-2007, Daniel J. Berger, All Rights Reserved
|
367
356
|
|
368
|
-
|
357
|
+
= License
|
369
358
|
Ruby's
|
370
359
|
|
371
|
-
|
360
|
+
= Warranty
|
372
361
|
This package is provided "as is" and without any express or
|
373
362
|
implied warranties, including, without limitation, the implied
|
374
363
|
warranties of merchantability and fitness for a particular purpose.
|
375
364
|
|
376
|
-
== Author
|
377
|
-
|
378
|
-
|
365
|
+
== Author(s)
|
366
|
+
* Daniel J. Berger
|
367
|
+
* Park Heesob
|