Tcl Windows API extension

The Windows task scheduler allows programs to be automatically started at certain times or when certain conditions are met. Tasks may be scheduled on either local or remote computers.

The simplest way to create and delete tasks is through the mstask_create and mstask_delete commands. These take care of acquiring and releasing the low lever interface handles and deal with the common case where a single task trigger is associated with a task.

More flexible and complete task scheduler functionality is available through commands that expose the interface handles to the different types of task scheduler objects. Working with the task scheduler involves three types of objects:

The task scheduler service which manages tasks
A task which is a unit of work scheduled by the task scheduler and is identified by a name unique to a system.
A task trigger which defines the conditions under which a task will be run. A task may have multiple associated task triggers.

An interface to the local or a remote task scheduler is obtained through the itaskscheduler_new command. The returned interface handle can be used to manage tasks on that computer. The commands itaskscheduler_get_target_system and itaskscheduler_set_target_system allow retrieving and changing the system associated with the task scheduler handle at any time.

Once a task scheduler interface handle is obtained, it can be used to access task definitions for that scheduler. The commands itaskscheduler_new_itask and itaskscheduler_get_itask will return interfaces to new and existing tasks which can be manipulated as described below. Tasks can also be deleted through the itaskscheduler_delete_task command and enumerated using itaskscheduler_get_tasks. Existence of a task definition can be verified using the itaskscheduler_task_exists command. (Note: as a general rule, commands related to tasks that require a task interface handle use itask in the command name while commands that require a task name use task.)

Once an interface handle to a task is obtained, its settings can be accessed and modified through the itask_get_info and itask_configure commands. Any changes made must be saved by then calling the itask_save command. Alternately, itask_edit_dialog may be used to display a dialog that allows the user to configure a task.

In addition to scheduling through the task scheduler, task execution can also be directly controlled. itask_run will immediately run a task while itask_end will terminate a task that is currently executing. Future times when a task will be run can be obtained using the itask_get_runtimes_within_interval call.

Each task is associated with zero or more task triggers that determine when and under what conditions the task is executed. The commands itask_new_itasktrigger and itask_get_itasktrigger return interface handles to new or existing task triggers. When not required triggers can be deleted through itask_delete_itasktrigger. The number of triggers associated with a task can be obtained through the itask_get_itasktrigger_count command. itask_get_itasktrigger_string returns a string describing the trigger.

Once a handle to a trigger is obtained, its settings can be retrieved and modified through the itasktrigger_get_info and itasktrigger_configure commands respectively.

Commands

itask_configure ITASK_HANDLE ?options?

Modifies the settings for the task associated with the handle ITASK_HANDLE. Note that the command itask_save must be called to save the changes.

The following options may be specified to change the settings for the task:

-account USERNAME	Sets USERNAME as the account under which the task will be run. If USERNAME is specified as the empty string, the task will be run under the system account. If any user other than the system account is specified, the -password option must also be specified.
-application PATH	Sets the application to be executed to PATH.
-comment COMMENT	Sets the comment for the task.
-creator NAME	Sets the task's creator name.
-data BINDATA	Stores BINDATA as the application-defined data for the task. BINDATA is treated as binary data.
-deletewhendone BOOLEAN	If specified as true, the task will be automatically deleted from the task scheduler when it has no more scheduled run times. Default is false.
-disabled BOOLEAN	If specified as true, the task is disabled and will not be run at its scheduled times. Default is false.
-dontstartonbatteries BOOLEAN	If specified as true, the task is not started at the scheduled time if the system is running on batteries. Default is false.
-hidden BOOLEAN	If specified as true, the task is hidden. Default is false.
-idlewait MINUTES	Sets the number of minutes that the system must be idle before the task runs.
-idlewaitdeadline MINUTES	Sets the maximum number of minutes that the task scheduler will wait for the system to become idle.
-killifonbatteries BOOLEAN	If specified as true, the task is not terminated if if the system is switches to batteries while the task is running. Default is false.
-killonidleend BOOLEAN	If specified as true, the task is terminated, if running, when the computer switches to a non-idle state (i.e. receives user input). Default is false.
-maxruntime MILLISECONDS	Sets the maximum time (in milliseconds) the application can run before it is terminated. If MILLISECONDS is specified as -1, there is no limit on the run time.
-params PARAMSTRING	Sets PARAMSTRING as the parameters to be passed to the application when the task is run.
-password PASSWORD	Specifies PASSWORD as the password associated with the user account specified with the -account option.
-priority PRIORITY	Sets the priority for the process executing the task. PRIORITY must be one of normal, abovenormal, belownormal, high, realtime, or idle.
-resumesystem BOOLEAN	If specified as true, the system will be awakened from a suspended state, if necessary, at the task's scheduled time. Default is false.
-restartonidleresume BOOLEAN	If specified as true, the task is restarted when the system goes into an idle state and the task had been previously terminated when the system went into a non-idle state. Default is false.
-runonlyifloggedon BOOLEAN	If specified as true, the task is only run if the user specified through the -account option is logged on. Default is false.
-startonlyifidle BOOLEAN	If specified as true, the task is only run if the system is idle at the task's scheduled run time. Default is false.
-workingdir PATH	Sets PATH as the working directory when the task is executed.

itask_delete_itasktrigger ITASK_HANDLE INDEX

Deletes the task trigger at position INDEX in the list of triggers for the task associated with handle ITASK_HANDLE.

itask_edit_dialog ITASK_HANDLE

Displays a dialog that allows the user to edit the task properties. Note that the dialog is modal and will lock out other windows until it is closed.

itask_end ITASK_HANDLE

Terminates (forcibly if necessary) the task associated with handle ITASK_HANDLE it it is running.

itask_get_info ITASK_HANDLE ?options?

Returns the settings for the task associated with handle ITASK_HANDLE. Any of the options described in itask_configure, except -password, may be specified to retrieve the corresponding setting. In addition, the command supports the following additional options:

-all	Returns all settings.
-lastruntime	Returns the last time that the task was run in the format Year-Month-Day Hour-Minutes-Seconds. An empty string is returned if the task has not been run yet.
-nextruntime	Returns the next time that the task is scheduled to run in the format Year-Month-Day Hour-Minutes-Seconds. The return value may also be one of disabled if the task is disabled, notriggers if no triggers are defined for it, or oneventonly if the task is configured to run on events as opposed to time.
-status	Returns the status of the task which is one of ready, running, disabled, partiallydefined, or unknown.

itask_get_itasktrigger ITASK_HANDLE INDEX

Returns an interface handle for an existing task trigger for the task associated with the handle ITASK_HANDLE. INDEX is the index of the trigger in the list of triggers defined for the task. When no longer required, the returned handle must be released by calling itasktrigger_release.

itask_get_itasktrigger_count ITASK_HANDLE

Returns the number of task triggers defined for the task associated with handle ITASK_HANDLE.

itask_get_itasktrigger_string ITASK_HANDLE INDEX

Returns a string description for an existing task trigger for the task associated with the handle ITASK_HANDLE. INDEX is the index of the trigger in the list of triggers defined for the task.

itask_get_runtimes_within_interval ?options?

Returns a list of times that the task is scheduled to run within a specified interval. Each item in the list is in the format Year-Month-Day Hour-Minutes-Seconds. The following options may be specified:

-count COUNT	The maximum number of time elements to return. COUNT must be less than 1440. The actual number returned may of course be less than COUNT depending on how many times the task is scheduled to run in the specified interval.
-end DATETIMESPEC	The ending time of the interval specified as Year-Month-Day Hour-Minutes-Seconds. By default, this is January 1, 2038.
-start DATETIMESPEC	The starting time of the interval specified as Year-Month-Day Hour-Minutes-Seconds. By default, this is the current time.
-statusvar VARNAME	If specified, VARNAME in the caller's context is set to the status of the call. This is success to indicate successful retrieval of the scheduled times. Otherwise, it may also be be one of disabled if the task is disabled, notriggers if no triggers are defined for it, or oneventonly if the task is configured to run on events as opposed to time. In all these three cases, the return value of the command is an empty list.

itask_new_itasktrigger ITASK_HANDLE

Creates a new task trigger for the task associated with the handle ITASK_HANDLE. The command returns a list of two elements. The first is the index of the newly created trigger in the list of triggers defined for the task. The second element is an interface handle to the newly defined task trigger. When no longer required, this must be released by calling itasktrigger_release.

itask_release ITASK_HANDLE

Releases resources associated with a task handle.

itask_run ITASK_HANDLE

Runs the task associated with handle ITASK_HANDLE.

itask_save ITASK_HANDLE

Saves any changes that have been made to the task associated with handle ITASK_HANDLE.

itaskscheduler_delete_task ITASKSCHEDULER_HANDLE TASKNAME

Deletes an existing task with name TASKNAME from the task scheduler associated with the handle ITASKSCHEDULER_HANDLE.

itaskscheduler_get_itask ITASKSCHEDULER_HANDLE TASKNAME

Returns an interface handle to an existing task with name TASKNAME. ITASKSCHEDULER_HANDLE is an interface handle to a task scheduler instance returned by itaskscheduler_new. The returned handle must be released by calling itask_release when it is no longer required.

itaskscheduler_get_target_system ITASKSCHEDULER_HANDLE

Returns the name of the system that the task scheduler associated with the handle ITASKSCHEDULER_HANDLE operates on.

itaskscheduler_get_tasks ITASKSCHEDULER_HANDLE

Returns a list of the names of the tasks contained in the task scheduler associated with the handle ITASKSCHEDULER_HANDLE.

itaskscheduler_new ?-system SYSTEMNAME?

Returns an interface handle to the task scheduler on the local system, or if the -system option is specified, on a remote system. The returned handle must be released by calling itaskscheduler_release when it is no longer required.

itaskscheduler_new_itask ITASKSCHEDULER_HANDLE TASKNAME

Creates a new task with name TASKNAME and returns an interface handle to it. ITASKSCHEDULER_HANDLE is an interface handle to a task scheduler instance returned by itaskscheduler_new. The returned handle must be released by calling itask_release when it is no longer required.

itaskscheduler_release ITASKSCHEDULER_HANDLE

Releases resources associated with a task scheduler handle returned by itaskscheduler_new.

itaskscheduler_set_target_system ITASKSCHEDULER_HANDLE SYSTEMNAME

Sets the task scheduler associated with the handle ITASKSCHEDULER_HANDLE to be the system identified by SYSTEMNAME.

itaskscheduler_task_exists ITASKSCHEDULER_HANDLE TASKNAME

Returns true if a new task with name TASKNAME exists in the task scheduler associated with handle ITASKSCHEDULER_HANDLE.

itasktrigger_configure ITASKTRIGGER_HANDLE ?options?

Configures the task trigger associated with the handle ITASKTRIGGER_HANDLE.

The following options may be specified to configure the task trigger:

-begindate DATESPEC	Specifies the date on which the trigger is activated. DATESPEC must be in the format YEAR-MONTH-DAY. Defaults to the current date.
-daysofmonth MONTHDAYMASK	Specifies the days of the month that the task is scheduled to run. MONTHDAYMASK is a bitmask with the low order bit corresponding to the first day of the month. This option only has effect if the value of the -type option is monthlydate.
-disabled BOOLEAN	If specified as true, disables the trigger so it has no effect. Default is false.
-duration MINUTES	Specifies the number of minutes after the task starts that the trigger is active. The task will be continuously restarted during this period with the interval between starts given by the option -interval.
-enddate DATESPEC	Specifies the date on which the trigger becomes inactive. DATESPEC must be in the format YEAR-MONTH-DAY. If DATESPEC is the empty string, there is no end date and the trigger never becomes inactive. This is also the default.
-interval MINUTES	See description of -duration.
-killatdurationend BOOLEAN	If specified as true, the task is terminated if it is still running at the end of the trigger duration. Default is false.
-months MONTHMASK	Specifies the months in which the trigger is active. MONTHMASK is a bitmask with the low order bit corresponding to January. The trigger is active in those months for which the corresponding bit is set. By default, the trigger is active for all months. This option is only used if the -type option specifies the trigger type to be either monthlydate or monthlydow.
-period PERIOD	If -type is daily, PERIOD is the number of days between invocations of the task. Similarly, if -type is weekly, PERIOD is the number of weeks between invocations of the task. This option is not used for other trigger types. If unspecified, this option defaults to 1.
-starttime TIMESPEC	Specifies the time at which the task is to be run. TIMESPEC is of the form HOUR:MINUTES.
-type TRIGGERTYPE	Specifies the type of the trigger. If TRIGGERTYPE is once, the task will only be run once. A value of daily or weekly will cause the task to be scheduled daily or weekly respectively. In both cases, the interval between runs being governed by the -period option. Furthermore, in the weekly case, the option -weekdays will control which days of the week the task is run. If TRIGGERTYPE is monthlydate, the task will be scheduled for the days defined by the -months and -daysofmonth options. A value of monthlydow allows the task to be scheduled during a specific week of a month. The -weekofmonth option specifies which week of the month, the -weekdays option specifies which days in that week, and -months option specifies which months are included. In addition, there are three trigger types that are event based - if TRIGGERTYPE is onidle, the trigger is activated when the system becomes idle, atsystemstart causes the task to run every time the system starts and atlogon causes it to run everytime the user logs on.
-weekdays WEEKMASK	Specifies the days of a week that the trigger should be activated. WEEKMASK is a bitmask corresponding to days of the week with the low order bit corresponding to Sunday. This option is only used if -type is specified as weekly or monthlydow.
-weekofmonth WEEKNUMBER	Specifies the week of the month that a task should be active. WEEKNUMBER must be an integer in the range 1-5 where 1-4 correspond to the first four weeks while a value of 5 corresponds to the last week of the month.

itasktrigger_get_info ITASKTRIGGER_HANDLE

Returns the settings for the task trigger associated with the handle ITASKTRIGGER_HANDLE. The settings are returned as a flat list of option value pairs. See itasktrigger_configure for information about the returned fields. Note that the returned fields depend on the trigger type as noted there.

itasktrigger_release ITASKTRIGGER_HANDLE

Releases resources associated with a task trigger handle.

mstask_create TASKNAME ?options?

This is command is a wrapper around that the various task scheduler interfaces that allows for easy creation of a task. It handles the common case where a task has a single associated trigger.

The command creates a new task based on the specified options. It accepts all the task related options as described for the itask_configure command. It associates a single trigger with the task and accepts all task trigger configuration options described for task triggers in itasktrigger_configure except for -disabled.

In addition, the command accepts the option -system which allows specification of which system the task is to be created on. By default, the task is created on the local system.

mstask_delete TASKNAME ?options?

This is command is a wrapper around that the various task scheduler interfaces that allows for easy deletion of a task. TASKNAME is the name that identifies the task.

The command accepts the option -system which allows specification of which system the task is to be deleted. By default, the task is deleted on the local system.

Task Scheduler

SYNOPSIS

DESCRIPTION

Overview

Commands

COPYRIGHT

TWAPI 2.0.12 Documentation