win32-taskscheduler 0.1.0 → 0.2.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 CHANGED
@@ -1,3 +1,15 @@
1
+ == 0.2.0 - 19-Jun-2009
2
+ * Rewritten in pure Ruby!
3
+ * The TaskScheduler::ONCE constant is now a valid trigger type. Thanks go to
4
+ Uri Iurgel for the spot and patch.
5
+ * Added the TaskScheduler#exists? method.
6
+ * Added the TaskScheduler#tasks alias for the TaskScheduler#enum method.
7
+ * The TaskScheduler#new_work_item method now accepts symbols as well as
8
+ strings for hash keys, and ignores case. Also, the keys are now validated.
9
+ * Renamed the example file and test file.
10
+ * Added the 'example' Rake task.
11
+ * Fixed some code in the README synopsis that was incorrect.
12
+
1
13
  == 0.1.0 - 11-May-2008
2
14
  * The TaskScheduler#save instance method now accepts an optional file name.
3
15
  * Most of the TaskScheduler setter methods now return the value specified
data/README CHANGED
@@ -6,28 +6,34 @@ Scheduler. It is analogous to the Unix cron daemon.
6
6
  require 'win32/taskscheduler'
7
7
  include Win32
8
8
 
9
- t = TaskScheduler.new
9
+ ts = TaskScheduler.new
10
10
 
11
+ # Create a trigger that starts on April 25, 2014 at 11:05 pm. The trigger
12
+ # will run on the first and last week of the month, on Monday and Friday,
13
+ # in the months of April and May.
14
+ #
11
15
  trigger = {
12
- :start_year => 2014,
13
- :start_month => 4,
14
- :start_day => 25,
15
- :start_hour => 23,
16
- :start_minute => 5,
17
- :trigger_type => TaskScheduler::MONTHLY_DOW,
18
- :type => {
19
- :weeks => TaskScheduler::FIRST | TaskScheduler::LAST,
20
- :days_of_week => TaskScheduler::MONDAY | TaskScheduler::FRIDAY,
21
- :months => TaskScheduler::APRIL | TaskScheduler::MAY
16
+ :start_year => 2014,
17
+ :start_month => 4,
18
+ :start_day => 25,
19
+ :start_hour => 23,
20
+ :start_minute => 5,
21
+ :trigger_type => TaskScheduler::MONTHLYDOW,
22
+ :type => {
23
+ :weeks => TaskScheduler::FIRST_WEEK | TaskScheduler::LAST_WEEK,
24
+ :days_of_week => TaskScheduler::MONDAY | TaskScheduler::FRIDAY,
25
+ :months => TaskScheduler::APRIL | TaskScheduler::MAY
22
26
  }
23
27
  }
24
28
 
25
- t.new_work_item('foo', trigger)
26
- t.application_name = 'notepad.exe'
27
- t.save
29
+ ts.new_work_item('foo', trigger)
30
+ ts.application_name = 'notepad.exe'
31
+ ts.save
28
32
 
29
33
  = Prerequisites
30
- Ruby 1.8.2 or later. Building from source requires VC++ 6.0 or later.
34
+ Ruby 1.8.2 or later.
35
+ Building from source requires VC++ 6.0 or later.
36
+ Windows XP or earlier. Vista and later not currently supported.
31
37
 
32
38
  = Installation
33
39
  rake install (non-gem) OR rake install_gem (gem)
data/Rakefile ADDED
@@ -0,0 +1,54 @@
1
+ require 'rake'
2
+ require 'rake/clean'
3
+ require 'rake/testtask'
4
+ require 'rbconfig'
5
+ include Config
6
+
7
+ =begin
8
+ desc "Cleans up the C related files created during the build"
9
+ task :clean do
10
+ Dir.chdir('ext') do
11
+ if File.exists?('taskscheduler.o') || File.exists?('taskscheduler.so')
12
+ sh 'nmake distclean'
13
+ end
14
+
15
+ if File.exists?('win32/taskscheduler.so')
16
+ File.delete('win32/taskscheduler.so')
17
+ end
18
+ end
19
+ end
20
+
21
+ desc "Builds, but does not install, the win32-taskscheduler library"
22
+ task :build => [:clean] do
23
+ Dir.chdir('ext') do
24
+ ruby 'extconf.rb'
25
+ sh 'nmake'
26
+ FileUtils.cp('taskscheduler.so', 'win32/taskscheduler.so')
27
+ end
28
+ end
29
+ =end
30
+
31
+ desc "Install the win32-taskscheduler library (non-gem)"
32
+ task :install => [:build] do
33
+ dir = File.join(Config::CONFIG['sitelibdir'], 'win32')
34
+ Dir.mkdir(dir) unless File.exists?(dir)
35
+ FileUtils.cp('lib/win32/taskscheduler.rb', dir)
36
+ end
37
+
38
+ desc 'Install the win32-taskscheduler library as a gem'
39
+ task :install_gem do
40
+ ruby 'win32-taskscheduler.gemspec'
41
+ file = Dir['win32-taskscheduler*.gem'].first
42
+ sh "gem install #{file}"
43
+ end
44
+
45
+ desc 'Run the example code'
46
+ task :example do
47
+ ruby '-Iib examples/taskscheduler_example.rb'
48
+ end
49
+
50
+ desc "Run the test suite for the win32-taskscheduler library"
51
+ Rake::TestTask.new do |t|
52
+ t.verbose = true
53
+ t.warning = true
54
+ end
@@ -0,0 +1,419 @@
1
+ = Description
2
+ This is an interface to the MS Windows task scheduler.
3
+ = Synopsis
4
+ require 'win32/taskscheduler'
5
+ include Win32
6
+
7
+ ts = TaskScheduler.new
8
+
9
+ # Create a trigger that starts on April 25, 2014 at 11:05 pm. The trigger
10
+ # will run on the first and last week of the month, on Monday and Friday,
11
+ # in the months of April and May.
12
+ #
13
+ trigger = {
14
+ :start_year => 2014,
15
+ :start_month => 4,
16
+ :start_day => 25,
17
+ :start_hour => 23,
18
+ :start_minute => 5,
19
+ :trigger_type => TaskScheduler::MONTHLYDOW,
20
+ :type => {
21
+ :weeks => TaskScheduler::FIRST_WEEK | TaskScheduler::LAST_WEEK,
22
+ :days_of_week => TaskScheduler::MONDAY | TaskScheduler::FRIDAY,
23
+ :months => TaskScheduler::APRIL | TaskScheduler::MAY
24
+ }
25
+ }
26
+
27
+ ts.new_work_item('my_task', trigger)
28
+ ts.application_name = 'notepad.exe'
29
+ ts.save
30
+
31
+ = Constants
32
+ === VERSION
33
+ Returns the current version number for this package as a string.
34
+
35
+ = Class Methods
36
+ === TaskScheduler.new(task_name=nil, trigger=nil)
37
+ Returns a new TaskScheduler object. If the task name and trigger are
38
+ passed as arguments, then a new work item is created and associated with
39
+ that trigger, although you can still activate other tasks with the same
40
+ object.
41
+
42
+ Passing arguments to the constructor is effectively a shortcut for
43
+ TaskScheduler.new plus TaskScheduler#new_work_item.
44
+
45
+ = Instance Methods
46
+ === TaskScheduler#account_information
47
+ Returns the account name associated with the task (but not the password).
48
+
49
+ === TaskScheduler#add_trigger(index, trigger)
50
+ Adds the given trigger at the specified index.
51
+
52
+ === TaskScheduler#activate(job_name)
53
+ Activates the given +job_name+.
54
+
55
+ === TaskScheduler#application_name
56
+ Returns the application associated with the task, i.e. the program that's
57
+ to run at the specified date and time.
58
+
59
+ === TaskScheduler#application_name=(name)
60
+ Sets the application associated with the task, i.e. the application
61
+ that runs at the specified date and time.
62
+
63
+ === TaskScheduler#comment
64
+ Returns the comment associated with the task.
65
+
66
+ === TaskScheduler#comment=
67
+ Sets the comment associated with the task.
68
+
69
+ === TaskScheduler#creator
70
+ Returns the name of the user who created the task.
71
+
72
+ === TaskScheduler#creator=(name)
73
+ Sets the name of the user who created the task.
74
+
75
+ === TaskScheduler#delete(task_name)
76
+ Deletes the task with the specified name.
77
+
78
+ === TaskScheduler#delete_trigger(index)
79
+ Deletes the trigger at the specified index.
80
+
81
+ === TaskScheduler#enum
82
+ Returns an array of task names.
83
+
84
+ === TaskScheduler#exit_code
85
+ Returns the exit code of from the task scheduler when it last attempted
86
+ to run the task.
87
+
88
+ === TaskScheduler#flags
89
+ Returns a list of flags that modify the behavior of the work item.
90
+
91
+ === TaskScheduler#flags=(flags)
92
+ Sets a list of flags that modify the behavior of the work item. See the
93
+ 'Task Flags' below for a list of valid flags.
94
+
95
+ === TaskScheduler#machine=(host)
96
+ Sets the active host. If this is not set, then it is assumed you are
97
+ working on the local host.
98
+
99
+ === TaskScheduler#max_run_time
100
+ Returns the maximum length of time, in milliseconds, the task can run
101
+ before terminating.
102
+
103
+ === TaskScheduler#max_run_time=(milliseconds)
104
+ Sets the maximum length of time, in milliseconds, the task can run
105
+ before terminating.
106
+
107
+ === TaskScheduler#most_recent_run_time
108
+ Returns a Time object indicating the most recent time the task ran.
109
+ Returns nil if the task has never run.
110
+
111
+ === TaskScheduler#new_work_item(task_name, trigger)
112
+ Creates a new task with the associated trigger. Note that the application
113
+ name hasn't been set, nor has it been saved.
114
+
115
+ === TaskSchedule#next_run_time
116
+ Returns a Time object indicating the next time the task will run.
117
+
118
+ === TaskScheduler#parameters
119
+ Returns the parameters that are passed to the scheduled command.
120
+
121
+ === TaskScheduler#parameters=(params)
122
+ Sets the parameters that are passed to the scheduled command.
123
+
124
+ === TaskScheduler#priority
125
+ Returns the priority level for the active task (Fixnum).
126
+
127
+ === TaskScheduler#priority=(level)
128
+ Sets the priority level for the active task. The priority of a task
129
+ determines the frequency and length of the time slices for a process.
130
+
131
+ See the 'Priority Levels' constants for a list of valid priorities.
132
+
133
+ === TaskScheduler#run
134
+ Executes the currently active task.
135
+
136
+ === TaskScheduler#save
137
+ Saves the current task. It also releases all information relative to tasks.
138
+ In order to modify this task again you must call Activate() because there
139
+ is no active task now.
140
+
141
+ === TaskScheduler#set_account_information(account_name, password)
142
+ Sets the account name and password used to run the task.
143
+
144
+ === TaskScheduler#status
145
+ Returns the status of the current task. The possible return values are
146
+ "ready", "running", "not scheduled" or "unknown", though the latter should
147
+ never occur.
148
+
149
+ In the case of "not scheduled", it means that one or more of the
150
+ properties that are needed to run the work item on a schedule
151
+ have not been set.
152
+
153
+ === TaskScheduler#terminate
154
+ Terminatest the execution of the active task.
155
+
156
+ === TaskScheduler#trigger(index)
157
+ Returns a hash that describes the trigger for the active task at the
158
+ given index.
159
+
160
+ === TaskScheduler#trigger=(trigger_hash){
161
+ Takes a hash that sets the various trigger values, i.e. when and how often
162
+ the task will run. Valid keys are:
163
+
164
+ * start_year # Must be >= current year
165
+ * start_month # 1-12
166
+ * start_day # 1-31
167
+ * start_hour # 0-23
168
+ * start_minute # 0-59
169
+ * end_year
170
+ * end_month
171
+ * end_day
172
+ * minutes_duration
173
+ * minutes_interval
174
+ * random_minutes_interval
175
+ * flags
176
+ * trigger_type
177
+ * type # A sub-hash
178
+
179
+ The +trigger_type+ determines what values are valid for the
180
+ +type+ key. They are as follows:
181
+
182
+ Trigger Type Valid +type+ keys
183
+ ============ ========================
184
+ DAILY days_interval
185
+ WEEKLY weeks_interval, days_of_week
186
+ MONTHLY_DATE months, days
187
+ MONTHLY_DOW weeks, days_of_week, months
188
+
189
+ === TaskScheduler#trigger_count
190
+ Returns the number of triggers associated with the active task.
191
+
192
+ === TaskScheduler#trigger_string
193
+ Returns a string that describes the current trigger for the active task.
194
+
195
+ === TaskScheduler#working_directory
196
+ Returns the current working directory for the active task.
197
+
198
+ === TaskScheduler#working_directory=(dir)
199
+ Sets the working directory for the scheduled command.
200
+
201
+ = Constants
202
+ == Standard Constants
203
+ === VERSION
204
+ Returns the current version number of this package as a String.
205
+
206
+ == Trigger Types
207
+ === ONCE
208
+ Trigger is set to run the task a single time. If this value is used, any
209
+ values used in the +type+ trigger key are ignored.
210
+
211
+ === DAILY
212
+ Trigger is set to run the task on a daily interval.
213
+
214
+ === WEEKLY
215
+ Trigger is set to run the work item on specific days of a specific week
216
+ of a specific month.
217
+
218
+ === MONTHLYDATE
219
+ Trigger is set to run the task on a specific day(s) of the month.
220
+
221
+ === MONTHLYDOW
222
+ Trigger is set to run the task on specific days, weeks, and months.
223
+
224
+ === ON_IDLE
225
+ Trigger is set to run the task if the system remains idle for the amount
226
+ of time specified by the idle wait time of the task.
227
+
228
+ === AT_SYSTEMSTART
229
+ Trigger is set to run the task at system startup. If this value is used,
230
+ any values used in the +type+ trigger key are ignored.
231
+
232
+ === AT_LOGON
233
+ Trigger is set to run the task when a user logs on. If this value is
234
+ used, any values used in the +type+ trigger key are ignored.
235
+
236
+ == Priority Levels
237
+ === IDLE
238
+ Typically used for system monitoring applications.
239
+
240
+ === BELOW_NORMAL
241
+ Between IDLE and NORMAL priority classes.
242
+
243
+ === NORMAL
244
+ The default priority class. Recommended for most applications.
245
+
246
+ === ABOVE_NORMAL
247
+ Between NORMAL and HIGH priority classes.
248
+
249
+ === HIGH
250
+ High priority. Use only for applications that need regular focus.
251
+
252
+ === REALTIME
253
+ Extremely high priority. May affect other applications. Not recommended
254
+ for most applications.
255
+
256
+ == Dates
257
+ === SUNDAY
258
+ The task will run on Sunday.
259
+
260
+ === MONDAY
261
+ The task will run on Monday.
262
+
263
+ === TUESDAY
264
+ The task will run on Tuesday.
265
+
266
+ === WEDNESDAY
267
+ The task will run on Wednesday.
268
+
269
+ === THURSDAY
270
+ The task will run on Thursday.
271
+
272
+ === FRIDAY
273
+ The task will run on Friday.
274
+
275
+ === SATURDAY
276
+ The task will run on Saturday.
277
+
278
+ === FIRST_WEEK
279
+ The task will run between the 1st and 7th day of the month.
280
+
281
+ === SECOND_WEEK
282
+ The task will run between the 8th and 14th day of the month.
283
+
284
+ === THIRD_WEEK
285
+ The task will run between the 15th and the 21st of the month.
286
+
287
+ === FOURTH_WEEK
288
+ The task will run between the 22nd and 28th day of the month.
289
+
290
+ === LAST_WEEK
291
+ The task will run between the last seven days of the month.
292
+
293
+ === JANUARAY
294
+ The task will run in January.
295
+
296
+ === FEBRUARY
297
+ The task will run in Februrary.
298
+
299
+ === MARCH
300
+ The task will run in March.
301
+
302
+ === APRIL
303
+ The task will run in April.
304
+
305
+ === MAY
306
+ The task will run in May.
307
+
308
+ === JUNE
309
+ The task will run in June.
310
+
311
+ === JULY
312
+ The task will run in July.
313
+
314
+ === AUGUST
315
+ The task will run in August.
316
+
317
+ === SEPTEMBER
318
+ The task will run in September.
319
+
320
+ === OCTOBER
321
+ The task will run in October.
322
+
323
+ === NOVEMBER
324
+ The task will run in November.
325
+
326
+ === DECEMBER
327
+ The task will run in December.
328
+
329
+ == Task Flags
330
+ === INTERACTIVE
331
+ This flag is used when converting Windows NT AT service jobs into work
332
+ items. The Windows NT AT service job refers to At.exe, the Windows NT
333
+ command-line utility used for creating jobs for the Windows NT Schedule
334
+ service. The Task Scheduler service replaces the Schedule service and is
335
+ backwards compatible with it. The conversion occurs when the Task
336
+ Scheduler is installed on Windows NT/Windows 2000 for example, if you
337
+ install Internet Explorer 4.0, or upgrade to Windows 2000. During the
338
+ setup process, the Task Scheduler installation code searches the registry
339
+ for jobs created for the AT service and creates work items that will
340
+ accomplish the same operation.
341
+
342
+ For such converted jobs, the interactive flag is set if the work item is
343
+ intended to be displayed to the user. When this flag is not set, no work
344
+ items are displayed in the Tasks folder, and no user interface associated
345
+ with the work item is presented to the user when the work item is
346
+ executed.
347
+
348
+ === DELETE_WHEN_DONE
349
+ The work item will be deleted when there are no more scheduled run times.
350
+
351
+ === DISABLED
352
+ The work item is disabled. This is useful to temporarily prevent a work
353
+ item from running at the scheduled time(s).
354
+
355
+ === HIDDEN
356
+ The work item created will be hidden.
357
+
358
+ === RUN_ONLY_IF_LOGGED_ON
359
+ The work item runs only if the user specified in +set_account_information+
360
+ is logged on interactively. This flag has no effect on work items set to
361
+ run in the local account.
362
+
363
+ === START_ONLY_IF_IDLE
364
+ The work item begins only if the computer is not in use at the scheduled
365
+ start time.
366
+
367
+ === SYSTEM_REQUIRED
368
+ The work item causes the system to be resumed, or awakened, if the system
369
+ is running on battery power. This flag is supported only on systems that
370
+ support resume timers.
371
+
372
+ === KILL_ON_IDLE_END
373
+ The work item terminates if the computer makes an idle to non-idle
374
+ transition while the work item is running. The computer is not
375
+ considered idle until the IdleWait triggers' time elapses with no user
376
+ input.
377
+
378
+ === RESTART_ON_IDLE_RESUME
379
+ The work item starts again if the computer makes a non-idle to idle
380
+ transition before all the work item's task triggers elapse.
381
+ (Use this flag in conjunction with KILL_ON_IDLE_END.)
382
+
383
+ === DONT_START_IF_ON_BATTERIES
384
+ The work item does not start if its target computer is running on
385
+ battery power.
386
+
387
+ === KILL_IF_GOING_ON_BATTERIES
388
+ The work item ends, and the associated application quits if the work
389
+ item's target computer switches to battery power.
390
+
391
+ = Notes
392
+ The terms "work item" and "task" are effectively synonymous for purposes
393
+ of this documentation.
394
+
395
+ = Known Bugs
396
+ The 'account_information()' method appears to be busted.
397
+
398
+ Please log all bug reports on the project page at
399
+ http://rubyforge.org/projects/win32utils
400
+
401
+ = Future Plans
402
+ Add support for Windows Vista and later.
403
+ Add support for IDLE, SYSTEMSTART and LOGON.
404
+
405
+ = Copyright
406
+ (C) 2003-2009 Daniel J. Berger, All Rights Reserved
407
+
408
+ = License
409
+ Ruby's
410
+
411
+ = Warranty
412
+ This package is provided "as is" and without any express or
413
+ implied warranties, including, without limitation, the implied
414
+ warranties of merchantability and fitness for a particular purpose.
415
+
416
+ = Authors and Testers
417
+ Park Heesob
418
+ Daniel J. Berger
419
+ Shashank Date