schtasks

package
v0.32.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 25, 2025 License: GPL-3.0 Imports: 19 Imported by: 0

Documentation

Rendered for windows/amd64

Overview

Schedule types on Windows: ========================== 1. one time:

  • at a specific date

2. daily:

  • 1 start date
  • recurring every n days

3. weekly:

  • 1 start date
  • recurring every n weeks
  • on specific weekdays

4. monthly:

  • 1 start date
  • on specific months
  • on specific days (1 to 31)

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrNotRegistered   = errors.New("task is not registered")
	ErrEmptyTaskName   = errors.New("task name cannot be empty")
	ErrInvalidTaskName = errors.New("invalid task name")
	ErrAccessDenied    = errors.New("access denied")
	ErrAlreadyExist    = errors.New("task already exists and cannot be updated in place")
)

Common errors

View Source
var (
	WeekDay  = &emptyString
	Month    = &emptyString
	AllWeeks = Weeks{[]string{"1", "2", "3", "4", "Last"}}
)

Functions

func Create

func Create(config *Config, schedules []*calendar.Event, permission Permission) error

Create or update a task (if the name already exists in the Task Scheduler)

func Delete

func Delete(title, subtitle string) error

Delete a task

func Status

func Status(title, subtitle string) error

Status returns the status of a task

Types

type Actions added in v0.30.0

type Actions struct {
	Context string       `xml:"Context,attr"`
	Exec    []ExecAction `xml:"Exec"`
}

type CalendarTrigger added in v0.30.0

type CalendarTrigger struct {
	StartBoundary            string                    `xml:"StartBoundary,omitempty"` // the date and time when the trigger is activated
	EndBoundary              string                    `xml:"EndBoundary,omitempty"`   // the date and time when the trigger is deactivated
	Repetition               *RepetitionPattern        `xml:"Repetition"`
	ExecutionTimeLimit       *period.Period            `xml:"ExecutionTimeLimit"` // the maximum amount of time that the task launched by this trigger is allowed to run
	Enabled                  *bool                     `xml:"Enabled"`            // indicates whether the trigger is enabled
	ScheduleByDay            *ScheduleByDay            `xml:"ScheduleByDay,omitempty"`
	ScheduleByWeek           *ScheduleByWeek           `xml:"ScheduleByWeek,omitempty"`
	ScheduleByMonth          *ScheduleByMonth          `xml:"ScheduleByMonth,omitempty"`
	ScheduleByMonthDayOfWeek *ScheduleByMonthDayOfWeek `xml:"ScheduleByMonthDayOfWeek,omitempty"`
}

type Compatibility added in v0.30.0

type Compatibility int

For scripting, gets or sets an integer value that indicates which version of Task Scheduler a task is compatible with.

const (
	TaskCompatibilityAT  Compatibility = iota // The task is compatible with the AT command.
	TaskCompatibilityV1                       // The task is compatible with Task Scheduler 1.0.
	TaskCompatibilityV2                       // The task is compatible with Task Scheduler 2.0.
	TaskCompatibilityV21                      // The task is compatible with Task Scheduler 2.1.
	TaskCompatibilityV22                      // The task is compatible with Task Scheduler 2.2.
	TaskCompatibilityV23                      // The task is compatible with Task Scheduler 2.3.
	TaskCompatibilityV24                      // The task is compatible with Task Scheduler 2.4.
)

type Config

type Config struct {
	ProfileName      string
	CommandName      string
	Command          string
	Arguments        string
	WorkingDirectory string
	JobDescription   string
	RunLevel         string
}

func Registered added in v0.30.0

func Registered() ([]Config, error)

type DaysOfMonth added in v0.30.0

type DaysOfMonth struct {
	Day []int `xml:"Day"`
}

type DaysOfWeek added in v0.30.0

type DaysOfWeek struct {
	Monday    *string `xml:"Monday"`
	Tuesday   *string `xml:"Tuesday"`
	Wednesday *string `xml:"Wednesday"`
	Thursday  *string `xml:"Thursday"`
	Friday    *string `xml:"Friday"`
	Sunday    *string `xml:"Sunday"`
	Saturday  *string `xml:"Saturday"`
}

type ExecAction added in v0.30.0

type ExecAction struct {
	Command          string `xml:"Command"`
	Arguments        string `xml:"Arguments"`
	WorkingDirectory string `xml:"WorkingDirectory,omitempty"`
}

type IdleSettings added in v0.30.0

type IdleSettings struct {
	Duration      period.Period `xml:"Duration"`      // the amount of time that the computer must be in an idle state before the task is run
	RestartOnIdle bool          `xml:"RestartOnIdle"` // whether the task is restarted when the computer cycles into an idle condition more than once
	StopOnIdleEnd bool          `xml:"StopOnIdleEnd"` // indicates that the Task Scheduler will terminate the task if the idle condition ends before the task is completed
	WaitTimeout   period.Period `xml:"WaitTimeout"`   // the amount of time that the Task Scheduler will wait for an idle condition to occur
}

IdleSettings specifies how the Task Scheduler performs tasks when the computer is in an idle condition.

type InstancesPolicy added in v0.30.0

type InstancesPolicy string

InstancesPolicy specifies what the Task Scheduler service will do when multiple instances of a task are triggered or operating at once.

const (
	MultipleInstancesParallel     InstancesPolicy = "Parallel"     // start new instance while an existing instance is running
	MultipleInstancesQueue        InstancesPolicy = "Queue"        // start a new instance of the task after all other instances of the task are complete
	MultipleInstancesIgnoreNew    InstancesPolicy = "IgnoreNew"    // do not start a new instance if an existing instance of the task is running
	MultipleInstancesStopExisting InstancesPolicy = "StopExisting" // stop an existing instance of the task before it starts a new instance
)

type LogonType added in v0.30.0

type LogonType string

LongType specifies the security logon method required to run those tasks associated with the principal. https://learn.microsoft.com/en-us/windows/win32/taskschd/taskschedulerschema-logontype-principaltype-element

const (
	LogonTypeServiceForUser   LogonType = "S4U"              // User must log on using a service for user (S4U) logon. When an S4U logon is used, no password is stored by the system and there is no access to the network or encrypted files.
	LogonTypePassword         LogonType = "Password"         // User must log on using a password.
	LogonTypeInteractiveToken LogonType = "InteractiveToken" // User must already be logged on. The task will be run only in an existing interactive session.
)

type Months added in v0.30.0

type Months struct {
	January   *string `xml:"January"`
	February  *string `xml:"February"`
	March     *string `xml:"March"`
	April     *string `xml:"April"`
	May       *string `xml:"May"`
	June      *string `xml:"June"`
	July      *string `xml:"July"`
	August    *string `xml:"August"`
	September *string `xml:"September"`
	October   *string `xml:"October"`
	November  *string `xml:"November"`
	December  *string `xml:"December"`
}

type Permission

type Permission int

Permission is a choice between System, User and User Logged On

const (
	UserAccount Permission = iota
	SystemAccount
	UserLoggedOnAccount
)

Permission available

type Principal added in v0.30.0

type Principal struct {
	ID        string    `xml:"id,attr"`
	UserId    string    `xml:"UserId"`
	LogonType LogonType `xml:"LogonType,omitempty"`
	RunLevel  RunLevel  `xml:"RunLevel,omitempty"`
}

type Principals added in v0.30.0

type Principals struct {
	Principal Principal `xml:"Principal"`
}

type RegistrationInfo added in v0.30.0

type RegistrationInfo struct {
	Date               string `xml:"Date"`
	Author             string `xml:"Author"`
	Description        string `xml:"Description"`
	URI                string `xml:"URI"`
	SecurityDescriptor string `xml:"SecurityDescriptor"` // https://learn.microsoft.com/en-us/windows/win32/secauthz/security-descriptor-string-format
}

type RepetitionPattern added in v0.30.0

type RepetitionPattern struct {
	Interval          period.Period `xml:"Interval"`          // the amount of time between each restart of the task. Required if RepetitionDuration is specified. Minimum time is one minute
	Duration          period.Period `xml:"Duration"`          // how long the pattern is repeated
	StopAtDurationEnd *bool         `xml:"StopAtDurationEnd"` // indicates if a running instance of the task is stopped at the end of the repetition pattern duration
}

RepetitionPattern defines how often the task is run and how long the repetition pattern is repeated after the task is started.

type RestartOnFailure added in v0.30.0

type RestartOnFailure struct {
	Count    uint          // the number of times that the Task Scheduler will attempt to restart the task
	Interval period.Period // specifies how long the Task Scheduler will attempt to restart the task
}

type RunLevel added in v0.30.0

type RunLevel string

The identifier that is used to specify the privilege level that is required to run the tasks that are associated with the principal. https://learn.microsoft.com/en-us/windows/win32/taskschd/taskschedulerschema-runleveltype-simpletype

const (
	RunLevelDefault        RunLevel = ""
	RunLevelLeastPrivilege RunLevel = "LeastPrivilege"
	RunLevelHighest        RunLevel = "HighestAvailable"
)

type ScheduleByDay added in v0.30.0

type ScheduleByDay struct {
	RandomDelay  *period.Period `xml:"RandomDelay,omitempty"` // a delay time that is randomly added to the start time of the trigger
	DaysInterval int            `xml:"DaysInterval"`
}

type ScheduleByMonth added in v0.30.0

type ScheduleByMonth struct {
	RandomDelay *period.Period `xml:"RandomDelay,omitempty"` // a delay time that is randomly added to the start time of the trigger
	Months      Months         `xml:"Months"`
	DaysOfMonth DaysOfMonth    `xml:"DaysOfMonth"`
}

type ScheduleByMonthDayOfWeek added in v0.30.0

type ScheduleByMonthDayOfWeek struct {
	RandomDelay *period.Period `xml:"RandomDelay,omitempty"` // a delay time that is randomly added to the start time of the trigger
	Months      Months         `xml:"Months"`
	Weeks       Weeks          `xml:"Weeks"`
	DaysOfWeek  DaysOfWeek     `xml:"DaysOfWeek"`
}

type ScheduleByWeek added in v0.30.0

type ScheduleByWeek struct {
	RandomDelay   *period.Period `xml:"RandomDelay,omitempty"` // a delay time that is randomly added to the start time of the trigger
	WeeksInterval int            `xml:"WeeksInterval"`
	DaysOfWeek    DaysOfWeek     `xml:"DaysOfWeek"`
}

type Settings added in v0.30.0

type Settings struct {
	AllowStartOnDemand         bool              `xml:"AllowStartOnDemand,omitempty"` // indicates that the task can be started by using either the Run command or the Context menu
	AllowHardTerminate         bool              `xml:"AllowHardTerminate,omitempty"` // indicates that the task may be terminated by the Task Scheduler service using TerminateProcess
	Compatibility              Compatibility     // indicates which version of Task Scheduler a task is compatible with
	DeleteExpiredTaskAfter     *period.Period    `xml:"DeleteExpiredTaskAfter,omitempty"` // the amount of time that the Task Scheduler will wait before deleting the task after it expires
	DisallowStartIfOnBatteries bool              `xml:"DisallowStartIfOnBatteries"`       // indicates that the task will not be started if the computer is running on batteries
	ExecutionTimeLimit         period.Period     `xml:"ExecutionTimeLimit"`               // the amount of time that is allowed to complete the task
	Hidden                     bool              `xml:"Hidden,omitempty"`                 // indicates that the task will not be visible in the UI
	IdleSettings               IdleSettings      `xml:"IdleSettings"`
	MultipleInstancesPolicy    InstancesPolicy   `xml:"MultipleInstancesPolicy"` // defines how the Task Scheduler deals with multiple instances of the task
	Priority                   uint              `xml:"Priority,omitempty"`      // the priority level of the task, ranging from 0 - 10, where 0 is the highest priority, and 10 is the lowest. Only applies to ComHandler, Email, and MessageBox actions
	RestartOnFailure           *RestartOnFailure `xml:"RestartOnFailure,omitempty"`
	RunOnlyIfIdle              bool              `xml:"RunOnlyIfIdle,omitempty"`             // indicates that the Task Scheduler will run the task only if the computer is in an idle condition
	RunOnlyIfNetworkAvailable  bool              `xml:"RunOnlyIfNetworkAvailable,omitempty"` // indicates that the Task Scheduler will run the task only when a network is available
	StartWhenAvailable         bool              `xml:"StartWhenAvailable,omitempty"`        // indicates that the Task Scheduler can start the task at any time after its scheduled time has passed
	StopIfGoingOnBatteries     bool              `xml:"StopIfGoingOnBatteries,omitempty"`    // indicates that the task will be stopped if the computer is going onto batteries
	WakeToRun                  bool              `xml:"WakeToRun,omitempty"`                 // indicates that the Task Scheduler will wake the computer when it is time to run the task, and keep the computer awake until the task is completed
	UseUnifiedSchedulingEngine bool              `xml:"UseUnifiedSchedulingEngine,omitempty"`
}

Settings provides the settings that the Task Scheduler service uses to perform the task https://docs.microsoft.com/en-us/windows/desktop/api/taskschd/nn-taskschd-itasksettings

type Task added in v0.30.0

type Task struct {
	XMLName          xml.Name         `xml:"Task"`
	Version          string           `xml:"version,attr"`
	Xmlns            string           `xml:"xmlns,attr"`
	RegistrationInfo RegistrationInfo `xml:"RegistrationInfo"`
	Triggers         Triggers         `xml:"Triggers"`
	Principals       Principals       `xml:"Principals"`
	Settings         Settings         `xml:"Settings"`
	Actions          Actions          `xml:"Actions"`
}

func NewTask added in v0.30.0

func NewTask() Task

func (*Task) AddExecAction added in v0.30.0

func (t *Task) AddExecAction(action ExecAction)

func (*Task) AddSchedules added in v0.30.0

func (t *Task) AddSchedules(schedules []*calendar.Event)

type TimeTrigger added in v0.30.0

type TimeTrigger struct {
	Enabled            *bool          `xml:"Enabled"` // indicates whether the trigger is enabled
	StartBoundary      string         `xml:"StartBoundary"`
	ExecutionTimeLimit *period.Period `xml:"ExecutionTimeLimit"`
	RandomDelay        *period.Period `xml:"RandomDelay,omitempty"` // a delay time that is randomly added to the start time of the trigger
}

type Triggers added in v0.30.0

type Triggers struct {
	CalendarTrigger []CalendarTrigger `xml:"CalendarTrigger,omitempty"`
	TimeTrigger     []TimeTrigger     `xml:"TimeTrigger,omitempty"`
}

type Weeks added in v0.30.0

type Weeks struct {
	Week []string `xml:"Week"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL