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 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
@@ -0,0 +1,16 @@
1
+ MANIFEST
2
+ CHANGES
3
+ README
4
+ extconf.rb
5
+
6
+ doc/daemon.txt
7
+ doc/service.txt
8
+
9
+ examples/daemon_test.rb
10
+ examples/services_test.rb
11
+
12
+ lib/win32/service.c
13
+ lib/win32/service.h
14
+
15
+ test/tc_daemon.rb
16
+ test/tc_service.rb
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.
@@ -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
@@ -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